mcp-documentation-server copilot-instructions.md

MCP Documentation Server - AI Coding Agent Instructions

Architecture Overview

This is a TypeScript-based Model Context Protocol (MCP) server providing document management and semantic search capabilities using local AI embeddings. Key architectural patterns:

• FastMCP Framework: Uses fastmcp library for MCP server implementation with Zod schema validation
• Modular Design: Core functionality split across DocumentManager, EmbeddingProvider, and utility modules
• Local-First Storage: All data stored in ~/.mcp-documentation-server/ (no database required)
• Lazy Loading: Embedding models load on-demand to avoid startup delays
• Chunk-Based Search: Documents split into chunks with embeddings for granular semantic search

Core Components

Server Entry Point (src/server.ts)

• Main FastMCP server with 8 MCP tools (add_document, search_documents, etc.)
• Uses #!/usr/bin/env node shebang - this file becomes the CLI executable
• Environment configuration via dotenv (loads .env files)
• Singleton DocumentManager instance with lazy initialization

Document Management (src/document-manager.ts logic in server.ts)

• Chunking Strategy: Text split into ~500-character chunks with overlap for better search
• ID Generation: Uses timestamp + random suffix pattern (see generateId())
• Storage: JSON files per document in data/ directory
• File Processing: Supports .txt, .md, .pdf via uploads folder workflow

Embedding Providers (src/embedding-provider.ts)

• Primary: TransformersEmbeddingProvider using @xenova/transformers (local ML)
• Fallback: SimpleEmbeddingProvider (hash-based, no ML dependencies)
• Model Selection: Via MCP_EMBEDDING_MODEL env var (default: Xenova/all-MiniLM-L6-v2)
• Critical: Model downloads (~420MB) on first use - implement timeouts

Development Workflows

Build & Run Commands

npm run build      # TypeScript compilation + executable permissions (shx chmod)
npm start          # Direct tsx execution (development)
npm run dev        # FastMCP dev mode with hot reload
npm run inspect    # FastMCP web UI for tool testing