@docsyncdev/mcp-server 1.0.0 → 1.1.1

package/README.md

@@ -1,4 +1,4 @@
-# @docsync/mcp-server
+# @docsyncdev/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.
 
@@ -8,6 +8,7 @@ MCP (Model Context Protocol) server for DocSync - enables AI coding assistants l
 - **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
+- **Compact Mode**: Condensed output for quick lookups (reduces token usage ~30%)
 - **Caching**: Built-in LRU cache reduces API calls and improves latency
 - **Rate Limiting**: Server-side rate limiting prevents abuse
 
@@ -36,7 +37,7 @@ Add to your `claude_desktop_config.json` or `.claude/settings.json`:
   "mcpServers": {
     "docsync": {
       "command": "npx",
-      "args": ["@docsync/mcp-server"],
+      "args": ["-y", "@docsyncdev/mcp-server"],
       "env": {
         "DOCSYNC_API_KEY": "ds_your_api_key_here",
         "DOCSYNC_PROJECT_ID": "your-project-uuid"
@@ -55,7 +56,7 @@ Add to your Cursor MCP configuration:
   "mcpServers": {
     "docsync": {
       "command": "npx",
-      "args": ["@docsync/mcp-server"],
+      "args": ["-y", "@docsyncdev/mcp-server"],
       "env": {
         "DOCSYNC_API_KEY": "ds_your_api_key_here",
         "DOCSYNC_PROJECT_ID": "your-project-uuid"
@@ -75,6 +76,7 @@ Search documentation semantically. Returns relevant chunks matching your query.
 
 - `query` (string, required): Natural language search query
 - `limit` (number, optional): Maximum results (default 10, max 50)
+- `compact` (boolean, optional): Return condensed output with just paths and scores (default: false)
 
 **Example:**
 
@@ -82,30 +84,34 @@ Search documentation semantically. Returns relevant chunks matching your query.
 How does authentication work in this project?
 ```
 
-### get_document
+**Compact mode example:**
 
-Retrieve full content of a specific document by ID.
-
-**Parameters:**
+```
+search_docs({ query: "authentication", compact: true })
 
-- `document_id` (string, required): Document ID from search results
+→ **5 results for "authentication"**
+  - docs/topics/auth.md (95%)
+  - docs/modules/security.md (82%)
+  - ...
+```
 
 ### get_docs_for_file ⭐
 
-**The killer feature.** Get documentation relevant to a source code file, with full hierarchy context.
+**The killer feature.** Get documentation relevant to a source code file, with full 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)
+- Unit doc (JWT implementation details) - **full content**
+- Module doc (Security architecture) - **full content**
+- Related topics based on concepts (Auth, Tokens, etc.) - **summaries only**
 
-All in one call. Full context pyramid.
+One call for immediate context. Related topics give you paths to dive deeper if needed.
 
 **Parameters:**
 
 - `file_path` (string, required): Path to the source code file
 - `include_content` (boolean, optional): Include full content (default: true)
+- `compact` (boolean, optional): Return condensed output for quick lookups (default: false)
 
 **Example:**
 
@@ -116,17 +122,44 @@ Get docs for src/services/payment-processor.ts
 Returns:
 
 ```
+# 📄 Unit Documentation
+## PaymentProcessor Class
+Detailed API for the payment processor...
+[full content]
+
 # 🏗️ Module Context
 ## Billing & Payments
 Overview of the billing system architecture...
+[full content]
 
-# 📚 Topic Context
-## Payment Processing
-How payments flow through the system...
+# 📚 Related Topics (3)
+- **Payment Processing** (payments)
+  Path: docs/topics/payments.md
+  How payments flow through the system
 
-# 📄 Related Documentation
-## PaymentProcessor Class
-Detailed API for the payment processor...
+- **Validation** (validation)
+  Path: docs/topics/validation.md
+  Input validation patterns
+
+- **Error Handling** (errors)
+  Path: docs/topics/errors.md
+  Error handling strategies
+```
+
+**Compact mode** returns summaries with topic list:
+
+```
+get_docs_for_file({ file_path: "src/auth/jwt.ts", compact: true })
+
+→ ## src/auth/jwt.ts
+  **JWT Handler**
+  Handles JWT token creation and validation
+
+  - **Module:** Security — Security patterns
+
+  **Related Topics (2):**
+  - Authentication (authentication): docs/topics/auth.md
+  - Token Management (tokens): docs/topics/tokens.md
 ```
 
 ### list_docs
@@ -136,6 +169,7 @@ Browse all documentation, optionally filtered by level.
 **Parameters:**
 
 - `level` (string, optional): Filter by "module", "topic", "unit", or "all" (default)
+- `compact` (boolean, optional): Return condensed output with just titles and paths (default: false)
 
 **Example:**
 
@@ -143,20 +177,31 @@ Browse all documentation, optionally filtered by level.
 List all module-level docs
 ```
 
+**Compact mode** returns a simple list without summaries:
+
+```
+list_docs({ level: "module", compact: true })
+
+→ **3 docs in MyProject**
+
+  **Module** (3)
+  - Authentication: docs/modules/auth.md
+  - Billing: docs/modules/billing.md
+  - API: docs/modules/api.md
+```
+
 ## 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) |
+| Variable             | Required | Description             |
+| -------------------- | -------- | ----------------------- |
+| `DOCSYNC_API_KEY`    | Yes      | Your DocSync API key    |
+| `DOCSYNC_PROJECT_ID` | Yes      | Your DocSync project ID |
 
 ## 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.
 
@@ -186,23 +231,7 @@ The document ID may be stale if documentation was recently updated. Run a new se
 
 ### 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
+1. Make sure your config uses `npx` with the `-y` flag: `"args": ["-y", "@docsyncdev/mcp-server"]`. The `-y` flag lets npx auto-install the package without prompting, which is required for MCP stdio communication.
+2. Check that your API key is valid in DocSync settings
+3. Verify your project ID is correct
+4. Ensure you have internet connectivity

package/dist/index.d.ts

@@ -52,6 +52,13 @@ interface ListDocsResponse {
     }>;
     count: number;
 }
+interface TopicSummary {
+    id: string;
+    file_path: string;
+    title: string;
+    concept: string;
+    summary: string | null;
+}
 interface FileDocsResponse {
     success: boolean;
     project_id: string;
@@ -59,8 +66,8 @@ interface FileDocsResponse {
     file_path: string;
     doc_path: string;
     unit_doc: DocInfo | null;
-    topic: DocInfo | null;
     module: DocInfo | null;
+    related_topics: TopicSummary[];
 }
 /**
  * Search results cache
@@ -82,6 +89,12 @@ interface ClientConfig {
     projectId: string;
     baseUrl?: string;
 }
+interface ClientMetadata {
+    hostname: string;
+    os: string;
+    editor: string | undefined;
+    version: string;
+}
 /**
  * DocSync API client for MCP server
  */
@@ -102,6 +115,18 @@ declare class DocSyncClient {
      * Get documentation related to a source file with hierarchy context
      */
     getDocsForFile(filePath: string, includeContent?: boolean): Promise<FileDocsResponse>;
+    /**
+     * Register a new MCP session with the server
+     */
+    registerSession(metadata: ClientMetadata): Promise<string>;
+    /**
+     * Send a heartbeat for an active session
+     */
+    heartbeat(sessionId: string): Promise<void>;
+    /**
+     * End an active session (graceful disconnect)
+     */
+    endSession(sessionId: string): Promise<void>;
     /**
      * Make authenticated request to DocSync API
      */
@@ -175,6 +200,7 @@ declare const searchToolDefinition: Tool;
 interface SearchToolInput {
     query: string;
     limit?: number;
+    compact?: boolean;
 }
 /**
  * Execute search_docs tool
@@ -194,6 +220,7 @@ declare const LIST_DOCS_TOOL_NAME = "list_docs";
 declare const listDocsToolDefinition: Tool;
 interface ListDocsToolInput {
     level?: 'module' | 'topic' | 'unit' | 'all';
+    compact?: boolean;
 }
 /**
  * Execute list_docs tool
@@ -204,12 +231,12 @@ declare function executeListDocsTool(client: DocSyncClient, input: ListDocsToolI
  * 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.
+ * with module context and related topics based on concepts.
  *
  * 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
+ * - Specific docs for the file/component (full content)
+ * - Module-level architecture (full content)
+ * - Related topics by concept (metadata only - fetch if needed)
  */
 
 declare const FILE_DOCS_TOOL_NAME = "get_docs_for_file";
@@ -220,6 +247,7 @@ declare const fileDocsToolDefinition: Tool;
 interface FileDocsToolInput {
     file_path: string;
     include_content?: boolean;
+    compact?: boolean;
 }
 /**
  * Execute get_docs_for_file tool