mcp-docs-service 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to the MCP Docs Service will be documented in this file.
+
+## [0.2.2] - 2024-03-12
+
+### Fixed
+
+- Fixed health check tool to properly access docs directory
+- Improved path validation to better handle relative paths
+- Enhanced CLI to support custom docs directory with `--docs-dir` and `--create-dir` options
+- Added better error handling and fallback for invalid paths
+
+### Added
+
+- Added troubleshooting section to health check documentation
+
+## [0.2.1] - 2023-03-15
+
+### Added
+
+- New `check_documentation_health` tool for analyzing documentation quality
+- Documentation health score calculation based on metadata completeness, broken links, and orphaned documents
+- Detailed issue reporting for documentation problems
+- Updated documentation with examples and usage guidelines for the health check tool
+
+## [0.2.0] - 2023-03-14
+
+### Added
+
+- Added proper CLI support with `npx mcp-docs-service`
+- Added support for custom docs directory with `--docs-dir` option
+- Added support for creating docs directory with `--create-dir` option
+- Added Cursor integration guide
+- Added Claude Desktop integration guide
+
+### Fixed
+
+- Fixed MCP response format to comply with the latest protocol
+- Fixed path validation for Windows paths
+- Fixed error handling for invalid paths
+
+## [0.1.0] - 2023-03-10
+
+### Added
+
+- Initial release with core documentation management features
+- Support for reading, writing, and editing markdown files with frontmatter
+- Support for listing documents and getting structure
+- Support for generating navigation
+- Support for searching documents
+- Support for generating knowledge bases for LLM context

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Your Name
+Copyright (c) 2023 Aleks Petrov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -7,9 +7,26 @@ The MCP Documentation Service is a custom implementation of the Model Context Pr
 - **Document Management**: Create, read, update, and delete markdown documentation files
 - **Metadata Management**: Work with document frontmatter (YAML metadata)
 - **Search**: Search through documentation using keywords and filters
+- **Knowledge Base Generation**: Create comprehensive knowledge bases for LLM context
+- **Structure Analysis**: Analyze documentation structure and relationships
+- **Navigation Generation**: Generate navigation structures for documentation
+- **Tag Management**: Organize documentation by tags and categories
 - **Analytics**: Analyze documentation health and get suggestions for improvement
 - **Custom Directory Support**: Specify a custom docs directory and create it if it doesn't exist
-- **JSON-RPC 2.0 Support**: Native support for the JSON-RPC 2.0 protocol used by Cursor and other MCP clients
+
+## Documentation
+
+Comprehensive documentation is available in the `docs` directory:
+
+- [Getting Started Guide](docs/guides/getting-started.md) - Introduction to the MCP Docs Manager
+- [API Overview](docs/api/overview.md) - Overview of the API and available tools
+- [Tools Reference](docs/api/tools-reference.md) - Complete reference of all available tools
+- [Features Overview](docs/features.md) - Comprehensive overview of all features
+- [Basic Usage Tutorial](docs/tutorials/basic-usage.md) - Tutorial for basic usage
+- [Examples](docs/examples/) - Code examples for common tasks
+  - [Navigation Generator](docs/examples/navigation-generator.md) - Example of how to generate navigation for documentation
+  - [Knowledge Base Generator](docs/examples/knowledge-base-generator.md) - Example of how to generate a knowledge base for LLM context
+- [Roadmap](docs/roadmap.md) - Development roadmap and planned features
 
 ## Installation
 
@@ -178,13 +195,9 @@ async function example() {
 example();
 ```
 
-## Query Formats
+## Query Format
 
-The service supports two query formats:
-
-### SQL-like Format
-
-The traditional SQL-like query format:
+The service uses a SQL-like query format to execute commands:
 
 ```
 command_name(param1="value1", param2="value2")
@@ -196,60 +209,20 @@ For example:
 get_document(path="architecture/overview.md")
 ```
 
-### JSON-RPC 2.0 Format
-
-As of version 0.2.0, the service also supports the JSON-RPC 2.0 format used by Cursor and other MCP clients:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "get_document",
-  "params": {
-    "path": "architecture/overview.md"
-  },
-  "id": 1
-}
-```
-
-The service automatically detects the format of the input and processes it accordingly.
-
 ## Available Commands
 
-### Document Operations
-
-- **list_files(directory="")**: List all markdown files (optionally in a specific directory)
-- **list_directories(directory="")**: List all directories (optionally in a specific directory)
-- **get_document(path="path/to/doc.md")**: Get a document's content and metadata
-- **create_document(path="path/to/doc.md", content="content", metadata={...})**: Create a new document
-- **update_document(path="path/to/doc.md", content="updated content", metadata={...})**: Update an existing document
-- **delete_document(path="path/to/doc.md")**: Delete a document
+### Documentation Tools
 
-### Search & Analysis
-
-- **search_documents(query="search term", directory="", tags=["tag1"], status="published")**: Search documents
-- **analyze_docs(directory="")**: Analyze documentation health
-- **get_health_score()**: Get overall documentation health score
-- **get_suggestions()**: Get suggestions for improving documentation
+- **read_document(path="path/to/doc.md")**: Read a markdown document and extract its content and metadata
+- **list_documents(basePath="")**: List all markdown documents in a directory
+- **get_structure(basePath="")**: Get the structure of the documentation directory
+- **get_navigation(basePath="")**: Get the navigation structure for the documentation
+- **get_docs_knowledge_base(basePath="", includeSummaries=true, maxSummaryLength=500)**: Create a comprehensive knowledge base of documentation for LLM context
+- **write_document(path="path/to/doc.md", content="content", metadata={...})**: Write content to a markdown document with frontmatter
+- **edit_document(path="path/to/doc.md", edits=[{oldText: "...", newText: "..."}])**: Apply edits to a markdown document while preserving frontmatter
+- **delete_document(path="path/to/doc.md")**: Delete a markdown document
+- **search_documents(basePath="", query="search term", tags=["tag1"], status="published")**: Search for markdown documents matching criteria
 
 ## License
 
 MIT
-
-Just published MCP Dcumentation Service 🔥
-Open source, vibe coding only.A tool that lets AI assistants interact with your documentation through the Model Context Protocol.It enables AI tools like Claude and Cursor to read, create, update, and analyze your markdown docs with a simple query interface.Key features:
-✅ Document CRUD operations with frontmatter support
-✅ Documentation search and health analytics
-✅ Custom directory handlingtest it: `npx mcp-docs-service`
-
-Why document your project when working with AI assistants like Claude in Cursor?Good documentation gives AI context about your project's architecture, decisions, and conventions. This means:• More accurate code suggestions
-• Better understanding of your codebase
-• Fewer misunderstandings and errors
-• Consistent implementation of patternsDocumentation is the map that helps AI navigate your code landscape.
-
-Use with Cursor IDE:1. Set up mcp-docs-service in your .cursor/mcp.json 2. Ask Cursor: "Analyze our documentation health" 3. Cursor uses MCP to scan your docs and report issues 4. Ask: "Create a guide for our authentication system" 5. Cursor generates a well-structured doc based on your codeThe AI can now read and write to your docs directory, keeping documentation in sync with code changes 💥
-
-With Claude Desktop:1. Configure mcp-docs-service in claude_desktop_config.json 2. Ask: "What's our approach to error handling?" 3. Claude searches your docs and explains your patterns 4. Say: "Our validation changed, update the API docs" 5. Claude updates the relevant markdown filesClaude becomes your documentation assistant, maintaining docs without switching contexts or tools.
-
-Real example from my workflow:"Claude, analyze our docs and identify gaps in our API documentation"Claude found 7 endpoints missing docs, created templates for each, and suggested improvements to our existing docs.This took 2 minutes instead of hours of manual review!Documentation becomes a living part of your codebase, not an afterthought.
-
-Getting started is simple:1. npm install -g mcp-docs-service 2. Add to your AI tool config 3. Start asking questions about your docsFull setup guide: npmjs.com/packa…This is just v0.1.1 - I'd love feedback on how you're using it and what features would help your documentation workflow.

package/dist/cli/bin.d.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 /**
- * MCP Documentation Management Service CLI
- * This is the entry point for the CLI when run via npx
+ * 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.
  */
-export {};
+import "../index.js";

package/dist/cli/bin.js

@@ -1,49 +1,53 @@
 #!/usr/bin/env node
-"use strict";
 /**
- * MCP Documentation Management Service CLI
- * This is the entry point for the CLI when run via npx
+ * 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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-const index_js_1 = require("./index.js");
+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);
 // Parse command line arguments
 const args = process.argv.slice(2);
-const options = {
-    docsDir: "./docs",
-    createIfNotExists: false,
-    help: false,
-};
-// Process arguments
+let docsDir = path.join(process.cwd(), "docs");
+let createDir = false;
+// Parse arguments
 for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--docs-dir" && i + 1 < args.length) {
-        options.docsDir = args[++i];
+    if (args[i] === "--docs-dir" && i + 1 < args.length) {
+        docsDir = path.resolve(args[i + 1]);
+        i++; // Skip the next argument
     }
-    else if (arg === "--create-dir") {
-        options.createIfNotExists = true;
-    }
-    else if (arg === "--help" || arg === "-h") {
-        options.help = true;
+    else if (args[i] === "--create-dir") {
+        createDir = true;
     }
 }
-// Show help if requested
-if (options.help) {
-    console.log(`
-MCP Documentation Service
-
-Usage:
-  npx mcp-docs-service [options]
-
-Options:
-  --docs-dir <path>  Specify the docs directory (default: ./docs)
-  --create-dir       Create the docs directory if it doesn't exist
-  --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 });
+            console.log(`Created docs directory: ${docsDir}`);
+        }
+    }
+    catch (error) {
+        console.error(`Error creating docs directory: ${error}`);
+        process.exit(1);
+    }
 }
-// Start the main process
-(0, index_js_1.main)(options).catch((error) => {
-    console.error("Fatal error:", error);
+// Ensure the docs directory exists
+if (!fs.existsSync(docsDir)) {
+    console.error(`Error: Docs directory does not exist: ${docsDir}`);
+    console.error(`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);
+// 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

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";;AAEA;;;GAGG;;AAEH,yCAAkC;AAElC,+BAA+B;AAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,OAAO,GAAG;IACd,OAAO,EAAE,QAAQ;IACjB,iBAAiB,EAAE,KAAK;IACxB,IAAI,EAAE,KAAK;CACZ,CAAC;AAEF,oBAAoB;AACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAEpB,IAAI,GAAG,KAAK,YAAY,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE;QAC/C,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;KAC7B;SAAM,IAAI,GAAG,KAAK,cAAc,EAAE;QACjC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;KAClC;SAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE;QAC3C,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;KACrB;CACF;AAED,yBAAyB;AACzB,IAAI,OAAO,CAAC,IAAI,EAAE;IAChB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;GAUX,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CACjB;AAED,yBAAyB;AACzB,IAAA,eAAI,EAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,4BAA4B;AAC5B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C,+BAA+B;AAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,IAAI,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;AAC/C,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,kBAAkB;AAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;IACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACpD,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,EAAE,CAAC,CAAC,yBAAyB;IAChC,CAAC;SAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,cAAc,EAAE,CAAC;QACtC,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,IAAI,SAAS,EAAE,CAAC;IACd,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,kCAAkC,KAAK,EAAE,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAC5B,OAAO,CAAC,KAAK,CAAC,yCAAyC,OAAO,EAAE,CAAC,CAAC;IAClE,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,+EAA+E;AAC/E,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAE3B,0BAA0B;AAC1B,OAAO,aAAa,CAAC;AAErB,+DAA+D;AAC/D,oFAAoF"}

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>;