@docsyncdev/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# @docsync/mcp-server
+
+MCP (Model Context Protocol) server for DocSync - enables AI coding assistants like Claude Code and Cursor to search and interact with your documentation.
+
+## Features
+
+- **Context-Aware Docs**: Get documentation for any source file with full hierarchy (unit → topic → module)
+- **Semantic Search**: Search your documentation using natural language queries
+- **Documentation Browser**: List and browse docs by level (module, topic, unit)
+- **Full Document Retrieval**: Get complete document content by ID
+- **Caching**: Built-in LRU cache reduces API calls and improves latency
+- **Rate Limiting**: Server-side rate limiting prevents abuse
+
+## Quick Start
+
+### 1. Get Your API Key
+
+1. Go to your DocSync dashboard at [docsync.dev](https://docsync.dev)
+2. Navigate to **Settings > API Keys**
+3. Click **Create API Key** and copy the key
+
+### 2. Get Your Project ID
+
+1. In DocSync dashboard, go to **Settings > API Keys**
+2. Select your project from the dropdown
+3. Copy the project ID from the generated config
+
+### 3. Configure Your AI Assistant
+
+#### Claude Code
+
+Add to your `claude_desktop_config.json` or `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "docsync": {
+      "command": "npx",
+      "args": ["@docsync/mcp-server"],
+      "env": {
+        "DOCSYNC_API_KEY": "ds_your_api_key_here",
+        "DOCSYNC_PROJECT_ID": "your-project-uuid"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to your Cursor MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "docsync": {
+      "command": "npx",
+      "args": ["@docsync/mcp-server"],
+      "env": {
+        "DOCSYNC_API_KEY": "ds_your_api_key_here",
+        "DOCSYNC_PROJECT_ID": "your-project-uuid"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### search_docs
+
+Search documentation semantically. Returns relevant chunks matching your query.
+
+**Parameters:**
+
+- `query` (string, required): Natural language search query
+- `limit` (number, optional): Maximum results (default 10, max 50)
+
+**Example:**
+
+```
+How does authentication work in this project?
+```
+
+### get_document
+
+Retrieve full content of a specific document by ID.
+
+**Parameters:**
+
+- `document_id` (string, required): Document ID from search results
+
+### get_docs_for_file ⭐
+
+**The killer feature.** Get documentation relevant to a source code file, with full hierarchy context.
+
+When you're working on `src/auth/jwt.ts`, this returns:
+
+- Related unit docs (JWT implementation details)
+- Parent topic doc (Authentication overview)
+- Grandparent module doc (Security architecture)
+
+All in one call. Full context pyramid.
+
+**Parameters:**
+
+- `file_path` (string, required): Path to the source code file
+- `include_content` (boolean, optional): Include full content (default: true)
+
+**Example:**
+
+```
+Get docs for src/services/payment-processor.ts
+```
+
+Returns:
+
+```
+# 🏗️ Module Context
+## Billing & Payments
+Overview of the billing system architecture...
+
+# 📚 Topic Context
+## Payment Processing
+How payments flow through the system...
+
+# 📄 Related Documentation
+## PaymentProcessor Class
+Detailed API for the payment processor...
+```
+
+### list_docs
+
+Browse all documentation, optionally filtered by level.
+
+**Parameters:**
+
+- `level` (string, optional): Filter by "module", "topic", "unit", or "all" (default)
+
+**Example:**
+
+```
+List all module-level docs
+```
+
+## Environment Variables
+
+| Variable             | Required | Description                      |
+| -------------------- | -------- | -------------------------------- |
+| `DOCSYNC_API_KEY`    | Yes      | Your DocSync API key             |
+| `DOCSYNC_PROJECT_ID` | Yes      | Your DocSync project ID          |
+| `DOCSYNC_API_URL`    | No       | Custom API URL (for development) |
+
+## Rate Limits
+
+- `search_docs`: 200 requests per hour
+- `get_docs_for_file`: 200 requests per hour
+- `list_docs`: 200 requests per hour
+- `get_document`: 500 requests per hour
+
+Rate limits are per API key. If you hit a rate limit, the tool will return an error message.
+
+## Caching
+
+The MCP server includes an in-memory LRU cache:
+
+- Cache size: 100 entries per cache type
+- TTL: 5 minutes
+- Repeated queries return cached results instantly
+
+Cache clears when the MCP server process restarts.
+
+## Troubleshooting
+
+### "DOCSYNC_API_KEY environment variable is required"
+
+Make sure you've added the `env` section to your MCP configuration with your API key.
+
+### "Rate limit exceeded"
+
+Wait a few minutes before making more requests. Consider if your agent is making too many searches.
+
+### "Document not found"
+
+The document ID may be stale if documentation was recently updated. Run a new search to get current document IDs.
+
+### Connection issues
+
+1. Check that your API key is valid in DocSync settings
+2. Verify your project ID is correct
+3. Ensure you have internet connectivity
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+DOCSYNC_API_KEY=your_key DOCSYNC_PROJECT_ID=your_project node dist/index.js
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+import { LRUCache } from 'lru-cache';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * LRU Cache for DocSync MCP Server
+ *
+ * Caches search results to reduce API calls and improve latency.
+ * AI agents often repeat similar queries, so caching provides significant benefits.
+ */
+
+interface SearchResult {
+    id: string;
+    file_path: string;
+    repository: string;
+    similarity: number;
+    metadata: {
+        type?: string;
+        level?: string;
+        concept?: string;
+        headerPath?: string[];
+    };
+}
+interface SearchResponse {
+    results: SearchResult[];
+    query: string;
+    credits_used: number;
+}
+interface DocInfo {
+    id: string;
+    file_path: string;
+    title: string;
+    level: string;
+    summary: string | null;
+    content?: string;
+    parent_path?: string | null;
+}
+interface ListDocsResponse {
+    success: boolean;
+    project_id: string;
+    project_name: string;
+    level: string;
+    docs: Array<{
+        id: string;
+        file_path: string;
+        repository_id: string;
+        repository_name: string;
+        title: string;
+        level: string;
+        parent_path: string | null;
+        summary: string | null;
+    }>;
+    count: number;
+}
+interface FileDocsResponse {
+    success: boolean;
+    project_id: string;
+    project_name: string;
+    file_path: string;
+    doc_path: string;
+    unit_doc: DocInfo | null;
+    topic: DocInfo | null;
+    module: DocInfo | null;
+}
+/**
+ * Search results cache
+ */
+declare const searchCache: LRUCache<string, SearchResponse, unknown>;
+/**
+ * Clear all caches (useful for testing or manual invalidation)
+ */
+declare function clearCaches(): void;
+
+/**
+ * DocSync API Client
+ *
+ * Wraps calls to DocSync edge functions with error handling and caching.
+ */
+
+interface ClientConfig {
+    apiKey: string;
+    projectId: string;
+    baseUrl?: string;
+}
+/**
+ * DocSync API client for MCP server
+ */
+declare class DocSyncClient {
+    private apiKey;
+    private projectId;
+    private baseUrl;
+    constructor(config: ClientConfig);
+    /**
+     * Search documentation semantically
+     */
+    search(query: string, limit?: number): Promise<SearchResponse>;
+    /**
+     * List documentation by level
+     */
+    listDocs(level?: 'unit' | 'topic' | 'module' | 'all'): Promise<ListDocsResponse>;
+    /**
+     * Get documentation related to a source file with hierarchy context
+     */
+    getDocsForFile(filePath: string, includeContent?: boolean): Promise<FileDocsResponse>;
+    /**
+     * Make authenticated request to DocSync API
+     */
+    private request;
+}
+/**
+ * Create a client from environment variables
+ */
+declare function createClientFromEnv(): DocSyncClient;
+
+/**
+ * DocSync MCP Server Implementation
+ *
+ * Implements the Model Context Protocol for AI coding assistants.
+ *
+ * ## AI Agent Instructions
+ *
+ * DocSync provides documentation context for codebases. Use these tools to understand
+ * code before modifying it, explain functionality to users, and navigate large codebases.
+ *
+ * ### Recommended Workflow
+ *
+ * **When user asks about a SPECIFIC FILE:**
+ * 1. Use `get_docs_for_file` with the file path → Returns unit doc + topic + module context
+ *    This is the PRIMARY tool for understanding specific code.
+ *
+ * **When user asks a CONCEPTUAL QUESTION:**
+ * 1. Use `search_docs` with natural language → Find relevant documentation
+ * 2. Use `get_docs_for_file` with file paths from search results for full context
+ *
+ * **When user wants an OVERVIEW:**
+ * 1. Use `list_docs` with level="module" → See high-level architecture
+ * 2. Drill down with level="topic" for feature areas
+ *
+ * ### Tool Selection Guide
+ *
+ * | User Intent                        | Tool to Use          |
+ * |------------------------------------|----------------------|
+ * | "Explain src/auth/jwt.ts"          | get_docs_for_file    |
+ * | "How does authentication work?"    | search_docs          |
+ * | "What's in this codebase?"         | list_docs            |
+ * | "Show me the billing module"       | list_docs → search   |
+ * | "I need to modify the API client"  | get_docs_for_file    |
+ *
+ * ### Key Principle
+ * ALWAYS fetch documentation context BEFORE explaining code or suggesting changes.
+ * The documentation contains architectural context, common patterns, and gotchas
+ * that may not be obvious from reading the source code alone.
+ */
+
+/**
+ * Create and configure the MCP server
+ */
+declare function createServer(client: DocSyncClient): Server;
+/**
+ * Start the MCP server with stdio transport
+ */
+declare function startServer(): Promise<void>;
+
+/**
+ * search_docs MCP Tool
+ *
+ * Enables AI agents to semantically search documentation in DocSync.
+ */
+
+declare const SEARCH_TOOL_NAME = "search_docs";
+/**
+ * Tool definition for MCP registration
+ */
+declare const searchToolDefinition: Tool;
+interface SearchToolInput {
+    query: string;
+    limit?: number;
+}
+/**
+ * Execute search_docs tool
+ */
+declare function executeSearchTool(client: DocSyncClient, input: SearchToolInput): Promise<CallToolResult>;
+
+/**
+ * list_docs MCP Tool
+ *
+ * Enables AI agents to browse documentation by level (module, topic, unit).
+ */
+
+declare const LIST_DOCS_TOOL_NAME = "list_docs";
+/**
+ * Tool definition for MCP registration
+ */
+declare const listDocsToolDefinition: Tool;
+interface ListDocsToolInput {
+    level?: 'module' | 'topic' | 'unit' | 'all';
+}
+/**
+ * Execute list_docs tool
+ */
+declare function executeListDocsTool(client: DocSyncClient, input: ListDocsToolInput): Promise<CallToolResult>;
+
+/**
+ * get_docs_for_file MCP Tool
+ *
+ * The killer feature: given a source code file, returns related documentation
+ * along with parent (topic) and grandparent (module) context.
+ *
+ * This gives agents full context about what they're working on:
+ * - Specific docs for the file/component
+ * - How it fits into the broader topic
+ * - The module-level architecture
+ */
+
+declare const FILE_DOCS_TOOL_NAME = "get_docs_for_file";
+/**
+ * Tool definition for MCP registration
+ */
+declare const fileDocsToolDefinition: Tool;
+interface FileDocsToolInput {
+    file_path: string;
+    include_content?: boolean;
+}
+/**
+ * Execute get_docs_for_file tool
+ */
+declare function executeFileDocsTool(client: DocSyncClient, input: FileDocsToolInput): Promise<CallToolResult>;
+
+export { type ClientConfig, DocSyncClient, FILE_DOCS_TOOL_NAME, type FileDocsToolInput, LIST_DOCS_TOOL_NAME, type ListDocsToolInput, SEARCH_TOOL_NAME, type SearchResponse, type SearchResult, type SearchToolInput, clearCaches, createClientFromEnv, createServer, executeFileDocsTool, executeListDocsTool, executeSearchTool, fileDocsToolDefinition, listDocsToolDefinition, searchCache, searchToolDefinition, startServer };