mcp-docs-service 0.3.10 → 0.3.11

package/README.md

@@ -1,111 +1,235 @@
 # MCP Documentation Service
 
-A Model Context Protocol (MCP) implementation for documentation management. This service provides tools for reading, writing, and managing markdown documentation.
+<a href="https://glama.ai/mcp/servers/icfujodcjd">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/icfujodcjd/badge" />
+</a>
+
+## What is it?
+
+MCP Documentation Service is a Model Context Protocol (MCP) implementation for documentation management. It provides a set of tools for reading, writing, and managing markdown documentation with frontmatter metadata. The service is designed to work seamlessly with AI assistants like Claude in Cursor or Claude Desktop, making it easy to manage your documentation through natural language interactions.
 
 ## Features
 
-- **Read and Write Documents**: Easily read and write markdown documents with frontmatter
-- **Edit Documents**: Make precise edits to documents with diff previews
+- **Read and Write Documents**: Easily read and write markdown documents with frontmatter metadata
+- **Edit Documents**: Make precise line-based edits to documents with diff previews
 - **List and Search**: Find documents by content or metadata
 - **Navigation Generation**: Create navigation structures from your documentation
-- **Health Checks**: Analyze documentation quality and identify issues
+- **Health Checks**: Analyze documentation quality and identify issues like missing metadata or broken links
+- **MCP Integration**: Seamless integration with the Model Context Protocol
+- **Frontmatter Support**: Full support for YAML frontmatter in markdown documents
+- **Markdown Compatibility**: Works with standard markdown files
 
-## Installation
+## Quick Start
 
-```bash
-npm install -g mcp-docs-service
-```
+### Installation
 
-Or use directly with npx:
+Requires Node to be installed on your machine.
 
 ```bash
-npx mcp-docs-service-npx /path/to/docs
+npm install -g mcp-docs-service
 ```
 
-> **Note**: When using with npx, use the `mcp-docs-service-npx` command to ensure proper stdio handling.
-
-## Usage
-
-### Command Line
+Or use directly with npx:
 
 ```bash
-# Use with default docs directory (./docs)
-mcp-docs-service
-
-# Specify a custom docs directory
-mcp-docs-service /path/to/docs
-
-# Create docs directory if it doesn't exist
-mcp-docs-service --create-dir
-
-# Run a health check on your documentation
-mcp-docs-service --health-check
+npx mcp-docs-service /path/to/docs
 ```
 
 ### Cursor Integration
 
-To use with Cursor, create a `.cursor/mcp.json` file with:
+To use with Cursor, create a `.cursor/mcp.json` file in your project root:
 
 ```json
 {
   "mcpServers": {
     "docs-manager": {
-      "command": "mcp-docs-service-cursor",
-      "args": ["/path/to/your/docs"],
-      "env": {
-        "NODE_ENV": "production",
-        "DEBUG": "mcp:*"
-      }
+      "command": "npx",
+      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
     }
   }
 }
 ```
 
-> **Note**: For Cursor integration, use the `mcp-docs-service-cursor` command instead of `mcp-docs-service`. This special wrapper ensures proper stdio handling for Cursor's MCP protocol communication.
+### Claude Desktop Integration
+
+To use MCP Docs Service with Claude Desktop:
+
+1. **Install Claude Desktop** - Download the latest version from [Claude's website](https://claude.ai/desktop).
 
-### NPX Integration
+2. **Configure Claude Desktop for MCP**:
 
-For Cursor integration with npx, use:
+   - Open Claude Desktop
+   - Click on the Claude menu and select "Developer Settings"
+   - This will create a configuration file at:
+     - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+     - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+3. **Edit the configuration file** to add the MCP Docs Service:
 
 ```json
 {
   "mcpServers": {
     "docs-manager": {
       "command": "npx",
-      "args": ["-y", "mcp-docs-service-npx", "/path/to/your/docs"],
-      "env": {
-        "NODE_ENV": "production",
-        "DEBUG": "mcp:*"
-      }
+      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
     }
   }
 }
 ```
 
-## Available Tools
+Make sure to replace `/path/to/your/docs` with the absolute path to your documentation directory.
+
+4. **Restart Claude Desktop** completely.
+
+5. **Verify the tool is available** - After restarting, you should see a green dot for docs-manager MCP tool (Cursor Settings > MCP)
+
+6. **Troubleshooting**:
+   - If the server doesn't appear, check the logs at:
+     - macOS: `~/Library/Logs/Claude/mcp*.log`
+     - Windows: `%APPDATA%\Claude\logs\mcp*.log`
+   - Ensure Node.js is installed on your system
+   - Make sure the paths in your configuration are absolute and valid
+
+## Examples
+
+### Using with Claude in Cursor
+
+When using Claude in Cursor, you can invoke the tools in two ways:
+
+1. **Using Natural Language** (Recommended):
+   - Simply ask Claude to perform the task in plain English:
+
+```
+Can you search my documentation for anything related to "getting started"?
+```
+
+```
+Please list all the markdown files in my docs directory.
+```
+
+```
+Could you check if there are any issues with my documentation?
+```
+
+2. **Using Direct Tool Syntax**:
+   - For more precise control, you can use the direct tool syntax:
 
-The service provides the following tools:
+```
+@docs-manager mcp_docs_manager_read_document path=docs/getting-started.md
+```
 
-- `read_document`: Read a markdown document
-- `write_document`: Create or overwrite a document
-- `edit_document`: Make precise edits to a document
-- `list_documents`: List all documents in a directory
-- `search_documents`: Find documents containing specific text
-- `generate_navigation`: Create a navigation structure
-- `check_documentation_health`: Analyze documentation quality
+```
+@docs-manager mcp_docs_manager_list_documents recursive=true
+```
 
-## Example
+```
+@docs-manager mcp_docs_manager_check_documentation_health
+```
+
+### Using with Claude Desktop
 
-Using with Claude in Cursor:
+When using Claude Desktop, you can invoke the tools in two ways:
+
+1. **Using Natural Language** (Recommended):
 
 ```
-@docs-manager read_document path=README.md
+Can you read the README.md file for me?
 ```
 
 ```
-@docs-manager edit_document path=README.md edits=[{"oldText":"# Documentation", "newText":"# Project Documentation"}]
+Please find all documents that mention "API" in my documentation.
 ```
 
+```
+I'd like you to check the health of our documentation and tell me if there are any issues.
+```
+
+2. **Using the Tool Picker**:
+   - Click the hammer icon in the bottom right corner of the input box
+   - Select "docs-manager" from the list of available tools
+   - Choose the specific tool you want to use
+   - Fill in the required parameters and click "Run"
+
+Claude will interpret your natural language requests and use the appropriate tool with the correct parameters. You don't need to remember the exact tool names or parameter formats - just describe what you want to do!
+
+### Common Tool Commands
+
+Here are some common commands you can use with the tools:
+
+#### Reading a Document
+
+```
+@docs-manager mcp_docs_manager_read_document path=docs/getting-started.md
+```
+
+#### Writing a Document
+
+```
+@docs-manager mcp_docs_manager_write_document path=docs/new-document.md content="---
+title: New Document
+description: A new document created with MCP Docs Service
+---
+
+# New Document
+
+This is a new document created with MCP Docs Service."
+```
+
+#### Editing a Document
+
+```
+@docs-manager mcp_docs_manager_edit_document path=README.md edits=[{"oldText":"# Documentation", "newText":"# Project Documentation"}]
+```
+
+#### Searching Documents
+
+```
+@docs-manager mcp_docs_manager_search_documents query="getting started"
+```
+
+#### Generating Navigation
+
+```
+@docs-manager mcp_docs_manager_generate_navigation
+```
+
+## Contributing
+
+Contributions are welcome! Here's how you can contribute:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Commit your changes: `git commit -am 'Add my feature'`
+4. Push to the branch: `git push origin feature/my-feature`
+5. Submit a pull request
+
+Please make sure your code follows the existing style and includes appropriate tests.
+
+## Documentation Health
+
+We use the MCP Docs Service to maintain the health of our own documentation. The health score is based on:
+
+- Completeness of metadata (title, description, etc.)
+- Presence of broken links
+- Orphaned documents (not linked from anywhere)
+- Consistent formatting and style
+
+You can check the health of your documentation with:
+
+```bash
+mcp-docs-service --health-check
+```
+
+## Documentation
+
+For more detailed information, check out our documentation:
+
+- [Getting Started Guide](https://github.com/alekspetrov/mcp-docs-service/blob/main/docs/guides/getting-started.md)
+- [MCP Integration Guide](https://github.com/alekspetrov/mcp-docs-service/blob/main/docs/guides/mcp-integration.md)
+- [MCP Protocol Usage](https://github.com/alekspetrov/mcp-docs-service/blob/main/docs/guides/mcp-protocol-usage.md)
+- [API Reference](https://github.com/alekspetrov/mcp-docs-service/blob/main/docs/api/tools-reference.md)
+- [Examples](https://github.com/alekspetrov/mcp-docs-service/blob/main/docs/examples/basic-usage.md)
+
 ## License
 
 MIT

package/dist/cli/bin.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * MCP Docs Service CLI
+ *
+ * This is the entry point for the CLI version of the MCP Docs Service.
+ * It simply imports and runs the main service.
+ */
+import "../index.js";

package/dist/cli/bin.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * MCP Docs Service CLI
+ *
+ * This is the entry point for the CLI version of the MCP Docs Service.
+ * It simply imports and runs the main service.
+ */
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+// Get the current directory
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Check if we're running under MCP Inspector
+const isMCPInspector = process.env.MCP_INSPECTOR === "true" ||
+    process.argv.some((arg) => arg.includes("modelcontextprotocol/inspector"));
+// Create a logging function that respects MCP Inspector mode
+const log = (...args) => {
+    if (!isMCPInspector) {
+        console.log(...args);
+    }
+};
+const errorLog = (...args) => {
+    console.error(...args);
+};
+// Parse command line arguments
+const args = process.argv.slice(2);
+log("CLI Arguments:", JSON.stringify(args));
+let docsDir = path.join(process.cwd(), "docs");
+let createDir = false;
+let healthCheck = false;
+let showHelp = false;
+// MCP Inspector specific handling
+// When run through MCP Inspector, it might pass arguments in a different format
+if (isMCPInspector) {
+    log("Detected MCP Inspector environment");
+    // Try to find a valid docs directory in all arguments
+    // This is a more aggressive approach but should work with various argument formats
+    for (const arg of process.argv) {
+        if (arg.endsWith("/docs") || arg.includes("/docs ")) {
+            const potentialPath = arg.split(" ")[0];
+            log("Found potential docs path in MCP Inspector args:", potentialPath);
+            if (fs.existsSync(potentialPath)) {
+                docsDir = path.resolve(potentialPath);
+                log("Using docs directory from MCP Inspector:", docsDir);
+                break;
+            }
+        }
+    }
+    // If we couldn't find a valid docs directory, use the default
+    log("Using docs directory:", docsDir);
+}
+else {
+    // Standard argument parsing
+    for (let i = 0; i < args.length; i++) {
+        log(`Processing arg[${i}]:`, args[i]);
+        if (args[i] === "--docs-dir" && i + 1 < args.length) {
+            docsDir = path.resolve(args[i + 1]);
+            log("Setting docs dir from --docs-dir flag:", docsDir);
+            i++; // Skip the next argument
+        }
+        else if (args[i] === "--create-dir") {
+            createDir = true;
+        }
+        else if (args[i] === "--health-check") {
+            healthCheck = true;
+        }
+        else if (args[i] === "--help" || args[i] === "-h") {
+            showHelp = true;
+        }
+        else if (!args[i].startsWith("--")) {
+            // Handle positional argument as docs directory
+            const potentialPath = path.resolve(args[i]);
+            log("Potential positional path:", potentialPath);
+            log("Path exists?", fs.existsSync(potentialPath));
+            if (fs.existsSync(potentialPath)) {
+                docsDir = potentialPath;
+                log("Setting docs dir from positional argument:", docsDir);
+            }
+            else {
+                log("Path doesn't exist, not using as docs dir:", potentialPath);
+            }
+        }
+    }
+}
+log("Final docs dir:", docsDir);
+// Show help if requested
+if (showHelp) {
+    console.log(`
+MCP Docs Service - Documentation Management Service
+
+Usage:
+  mcp-docs-service [options]
+  mcp-docs-service <docs-directory> [options]
+
+Options:
+  --docs-dir <path>   Specify the docs directory (default: ./docs)
+  --create-dir        Create the docs directory if it doesn't exist
+  --health-check      Run a health check on the documentation
+  --help, -h          Show this help message
+  `);
+    process.exit(0);
+}
+// Create docs directory if it doesn't exist and --create-dir is specified
+if (createDir) {
+    try {
+        if (!fs.existsSync(docsDir)) {
+            fs.mkdirSync(docsDir, { recursive: true });
+            log(`Created docs directory: ${docsDir}`);
+        }
+    }
+    catch (error) {
+        errorLog(`Error creating docs directory: ${error}`);
+        process.exit(1);
+    }
+}
+// Ensure the docs directory exists
+if (!fs.existsSync(docsDir)) {
+    errorLog(`Error: Docs directory does not exist: ${docsDir}`);
+    errorLog(`Use --create-dir to create it automatically`);
+    process.exit(1);
+}
+// Add the docs directory to process.argv so it's available to the main service
+process.argv.push(docsDir);
+// Add health check flag to process.argv if specified
+if (healthCheck) {
+    process.argv.push("--health-check");
+}
+// Import the main service
+import "../index.js";
+// The main service will handle the CLI arguments and execution
+// No additional code needed here as the main index.ts already has CLI functionality
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":"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"}

package/dist/handlers/docs.d.ts

@@ -0,0 +1,26 @@
+import { ToolResponse } from "../types/tools.js";
+/**
+ * Reads a markdown document and extracts its content and metadata
+ */
+export declare function readDocument(docPath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Lists all markdown documents in a directory
+ */
+export declare function listDocuments(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Gets the structure of the documentation directory
+ */
+export declare function getStructure(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Gets the navigation structure for the documentation
+ */
+export declare function getNavigation(basePath: string, allowedDirectories: string[]): Promise<ToolResponse>;
+/**
+ * Checks the health of documentation
+ */
+export declare function checkDocumentationHealth(basePath: string, options: {
+    checkLinks?: boolean;
+    checkMetadata?: boolean;
+    checkOrphans?: boolean;
+    requiredMetadataFields?: string[];
+}, allowedDirectories: string[]): Promise<ToolResponse>;