MCP Documentation Server

The project is organized into several key modules located in the src/ directory:

• server.ts: The main MCP server implementation.
• document-manager.ts: Handles document storage and retrieval.
• embedding-provider.ts: Provides an abstraction for AI embedding models.
• search-engine.ts: Implements semantic search functionality.
• types.ts: Contains TypeScript type definitions.
• utils.ts: General utility functions.

Key Technologies Used:

• FastMCP: The framework used for building the MCP server.
• @xenova/transformers: Used for running local AI embedding models.
• pdf-ts: Used for extracting text from PDF files.
• Zod: Used for runtime type validation.

The server uses local embeddings via Transformers.js. You can select different models using the MCP_EMBEDDING_MODEL variable:

⚠️ Important: Changing the embedding model requires re-adding all documents. Embeddings from different models are incompatible. The Orama database is recreated automatically when the dimension changes.

The server uses an IntelligentChunker that implements the Parent-Child Chunking pattern to improve search accuracy and context retrieval:

1. Parent Chunks: Documents are first split into large parent chunks that preserve full context (such as sections or paragraphs).
2. Child Chunks: Each parent is further split into small child chunks used for precise vector similarity search.
3. Retrieval: When a query matches a child chunk, the system retrieves the corresponding parent chunk. This ensures the LLM receives both the specific matched fragment and the broader context surrounding it.

If you discover a security vulnerability, please report it responsibly using one of the following methods:

1. Email: Send details to andreabravaccino@gmail.com.
2. GitHub Issues: Use the issue tracker for non-sensitive issues.
3. Security Advisories: Use GitHub's private vulnerability reporting for sensitive vulnerabilities.

What to include in your report

• A description of the vulnerability.
• Steps to reproduce the issue.
• A potential impact assessment.
• A suggested fix (if available).
• Your contact information for follow-up.

Response Timeline

• Initial Response: Within 48 hours.
• Status Updates: Weekly updates during investigation.
• Resolution: Target of 30 days for fixes, depending on severity.

Before submitting a Pull Request, follow these steps to ensure a smooth review process:

1. Sync with upstream: Fetch and rebase your branch on upstream/main.

   git fetch upstream
   git rebase upstream/main

2. **Verify Build**: Ensure `npm run build` passes.
3. **Manual Testing**: Use `npm run inspect` to test the MCP functionality manually.
4. **Documentation**: Update relevant documentation if your changes affect existing features.

**PR Requirements**:
- Use a **clear title** following the conventional commit format.
- Provide a **description** explaining the *what*, *why*, and *how*.
- Describe your **testing methodology**.
- Explicitly mark any **breaking changes**.
- Include **screenshots** for any changes to the inspector UI.

To maintain a secure environment when using the MCP Documentation Server, follow these practices:

• Keep updated: Always use the latest stable version.
• Manage files: Regularly review uploaded documents and clean up unused files.
• Permissions: Use proper file system permissions for the ~/.mcp-documentation-server/ directory.
• Validation: Validate document sources before processing.
• Monitoring: Monitor system resources during embedding generation.

The server includes a graphical web interface at http://127.0.0.1:3080. This is ideal for visual exploration and manual operations:

• Dashboard: Overview of documents and statistics.
• Documents: Browse, view, and delete documents.
• Add Document: Create documents with title, content, and metadata.
• Search: Perform semantic searches across all or specific documents.
• AI Search: Gemini-powered analysis (requires GEMINI_API_KEY).
• Upload Files: Drag-and-drop .txt, .md, or .pdf files.
• Context Window: Interactively explore chunks around a specific index.

While the server provides MCP tools, interacting via the REST API is recommended for AI agents (like Claude Code, Cursor, or Gemini CLI). This approach avoids bloating the conversation context with large MCP tool schemas, as only the JSON responses are sent to the LLM.

The API is available at http://127.0.0.1:3080/api/.

Example API Calls

Get configuration:

curl -s http://127.0.0.1:3080/api/config

List documents:

curl -s http://127.0.0.1:3080/api/documents

Perform a search:

curl -s -X POST http://127.0.0.1:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

Install the Agent Skill

You can install a pre-made skill that teaches your agent how to use these endpoints:

npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server

When contributing code, adhere to these guidelines:

TypeScript Guidelines

• Use Strict mode settings.
• Prefer explicit types over any.
• Use interfaces for defining object shapes.
• Use async/await instead of raw Promises.
• Implement robust error handling.

Code Style and Organization

• Follow the Single Responsibility Principle (one class/function per file where appropriate).
• Use descriptive naming for files and functions.
• Use named exports instead of default exports where possible.
• Provide JSDoc comments for all public methods and classes.