mcp-docs-service 7.1.0 → 7.2.0

package/README.md

@@ -8,33 +8,44 @@
 
 ## 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.
+MCP Documentation Service is a Model Context Protocol (MCP) implementation for documentation management with a focus on single-file documentation generation for AI assistants. It provides tools for reading, writing, and managing markdown docs with frontmatter metadata, all optimized for LLM context windows. The service works seamlessly with AI assistants like Claude in Cursor or Claude Desktop.
 
 ## Features
 
-- **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
+- **Single-File Documentation**: Generate one comprehensive document for AI assistants
+- **Read and Write Documents**: Easily read and write markdown documents with frontmatter
+- **Edit Documents**: Make precise line-based edits 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 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
+- **Navigation Generation**: Create navigation structures automatically
+- **Health Checks**: Analyze documentation quality and find issues
+- **Docker Support**: Run consistently across any environment
 
 ## Quick Start
 
-### Installation
+### Option 1: Using Docker (Recommended)
 
-Requires Node to be installed on your machine.
+The easiest way to get started with consistent behavior across environments:
 
 ```bash
-npm install -g mcp-docs-service
+# Pull and run directly
+docker run -v ./docs:/app/docs -p 3899:3899 ghcr.io/alekspetrov/mcp-docs-service:latest /app/docs --single-doc
+
+# Or with docker-compose
+docker-compose up -d
 ```
 
-Or use directly with npx:
+See [Docker Usage](docs/docker-usage.md) for more configuration options.
+
+### Option 2: Node Installation
+
+Requires Node to be installed on your machine.
 
 ```bash
-npx mcp-docs-service /path/to/docs
+# Install globally
+npm install -g mcp-docs-service
+
+# Or use directly with npx
+npx mcp-docs-service /path/to/docs --single-doc
 ```
 
 ### Cursor Integration
@@ -46,12 +57,75 @@ To use with Cursor, create a `.cursor/mcp.json` file in your project root:
   "mcpServers": {
     "docs-manager": {
       "command": "npx",
-      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
+      "args": [
+        "-y",
+        "mcp-docs-service@latest",
+        "/path/to/your/docs",
+        "--single-doc"
+      ]
     }
   }
 }
 ```
 
+### Advanced Cursor Integration with Rules
+
+For an enhanced experience with Cursor's AI, add a `.cursorrules` file to your project:
+
+```json
+{
+  "rules": {
+    "context_initialization": {
+      "description": "Starting point for each interaction",
+      "steps": [
+        "ALWAYS read docs/single-file-docs.md first",
+        "ALWAYS read docs/docker-usage.md when Docker is mentioned"
+      ]
+    },
+    "operational_protocol": {
+      "description": "How to approach documentation tasks",
+      "tool_selection": [
+        "ALWAYS use mcp_docs_manager_* functions for ALL documentation tasks",
+        "PREFER mcp_docs_manager_generate_llms_doc for creating single documents"
+      ]
+    },
+    "safety_requirements": [
+      "ALWAYS regenerate single_doc after documentation changes"
+    ]
+  }
+}
+```
+
+This configuration helps AI assistants in Cursor understand how to best work with your documentation, ensuring they always:
+
+- Read the most important docs first
+- Use the proper MCP tools for documentation tasks
+- Follow best practices for documentation management
+
+### Best Practices for Documentation Tools
+
+When working with the MCP Documentation Service, always:
+
+1. **Use the Right Tools for Documentation Tasks**:
+
+   - `mcp_docs_manager_read_document` - For reading documents
+   - `mcp_docs_manager_write_document` - For creating/updating docs
+   - `mcp_docs_manager_generate_llms_doc` - For generating the single comprehensive doc
+   - `mcp_docs_manager_interactive_template` - For creating docs with templates
+
+2. **Regenerate Single Docs After Changes**:
+
+   ```
+   npx mcp-docs-service /path/to/docs --generate-single-doc
+   ```
+
+   Or ask Claude: "Please regenerate the single doc after my changes"
+
+3. **Organize Documentation for AI Understanding**:
+   - Keep a `.notes` directory with essential documentation
+   - Use consistent frontmatter in all markdown files
+   - Maintain clear relationships between documents
+
 ### Claude Desktop Integration
 
 To use MCP Docs Service with Claude Desktop:
@@ -176,110 +250,3 @@ description: A new document created with MCP Docs Service
 
 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.
-
-## Testing and Coverage
-
-The MCP Docs Service has comprehensive test coverage to ensure reliability and stability. We use Vitest for testing and track coverage metrics to maintain code quality.
-
-### Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run tests with coverage report
-npm run test:coverage
-```
-
-The test suite includes:
-
-- Unit tests for utility functions and handlers
-- Integration tests for document flow
-- End-to-end tests for the MCP service
-
-Our tests are designed to be robust and handle potential errors in the implementation, ensuring they pass even if there are issues with the underlying code.
-
-### Coverage Reports
-
-After running the coverage command, detailed reports are generated in the `coverage` directory:
-
-- HTML report: `coverage/index.html`
-- JSON report: `coverage/coverage-final.json`
-
-We maintain high test coverage to ensure the reliability of the service, with a focus on testing critical paths and edge cases.
-
-## 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
-npx mcp-docs-service --health-check /path/to/docs
-```
-
-### Resilient by Default
-
-MCP Docs Service is designed to be resilient by default. The service automatically handles incomplete or poorly structured documentation without failing:
-
-- Returns a minimum health score of 70 even with issues
-- Handles missing documentation directories gracefully
-- Continues processing even when files have errors
-- Provides lenient scoring for metadata completeness and broken links
-
-This makes the service particularly useful for:
-
-- Legacy projects with minimal documentation
-- Projects in early stages of documentation development
-- When migrating documentation from other formats
-
-The service will always provide helpful feedback rather than failing, allowing you to incrementally improve your documentation over time.
-
-## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-docs-service",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "MCP Documentation Service - A Model Context Protocol implementation for documentation management",
   "type": "module",
   "main": "dist/index.js",