Metadata-Version: 2.4
Name: your-docs-mcp
Version: 0.0.4
Summary: Model Context Protocol server for hierarchical documentation navigation with markdown and OpenAPI support
Author: MCP Contributors
License: MIT
Project-URL: Homepage, https://github.com/esola-thomas/Markdown-MCP
Project-URL: Repository, https://github.com/esola-thomas/Markdown-MCP
Keywords: mcp,documentation,ai,openapi,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: openapi-spec-validator>=0.7.0
Requires-Dist: prance>=23.6.21.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: chromadb>=0.4.0
Requires-Dist: sentence-transformers>=2.2.2
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Dynamic: license-file

# Documentation MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to navigate and query documentation through hierarchical structures, supporting markdown files with YAML frontmatter and OpenAPI 3.x specifications.

## Features

- **Hierarchical Navigation**: Navigate documentation organized in nested directory structures with unlimited depth
- **Markdown Support**: Parse markdown files with YAML frontmatter metadata (title, tags, category, order)
- **OpenAPI Integration**: Load and query OpenAPI 3.x specifications as documentation resources
- **Intelligent Search**: Full-text search with metadata filtering and hierarchical context
- **Web Interface**: Built-in web server provides browser-based access to documentation with the same tools available to LLMs
- **Cross-Platform**: Works with Claude Desktop, VS Code/GitHub Copilot, and other MCP-compatible AI assistants
- **Security**: Built-in path validation, query sanitization, and audit logging
- **Performance**: Caching with TTL and automatic file change detection

## Quick Start

### Installation

```bash
# Install from PyPI
pip install your-docs-mcp

# Or install from source
git clone https://github.com/esola-thomas/Markdown-MCP
cd Markdown-MCP
pip install -e .
```

### Basic Configuration

1. Set your documentation root directory:

```bash
export DOCS_ROOT=/path/to/your/docs
```

2. Start the MCP server:

```bash
your-docs-mcp
```

### Claude Desktop Configuration

Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "docs": {
      "command": "your-docs-mcp",
      "env": {
        "DOCS_ROOT": "/absolute/path/to/your/docs"
      }
    }
  }
}
```

### VS Code Configuration

Create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "docs": {
      "command": "your-docs-mcp",
      "env": {
        "DOCS_ROOT": "${workspaceFolder}/docs"
      }
    }
  }
}
```

### Try the Example

This repository includes a complete example documentation structure in the [`example/`](example/) folder that you can use to test the MCP server or as a template for your own documentation.

**Quick test:**

```bash
# Point DOCS_ROOT to the example folder
export DOCS_ROOT=/path/to/Markdown-MCP/example

# Start the server
your-docs-mcp
```

The example includes:
- Hierarchical documentation structure with nested categories
- Markdown files with proper YAML frontmatter
- Sample API documentation and guides
- OpenAPI 3.0 specification example
- Comprehensive README explaining the structure

See the [`example/README.md`](example/README.md) for detailed information about the structure and how to customize it for your project.

## Web Interface

The Markdown MCP server includes a built-in web interface that allows users to browse and search documentation directly in their browser, using the same tools available to AI assistants.

### Accessing the Web Interface

When you start the server, it automatically launches both the MCP server (for AI assistants) and a web server (for browser access):

```bash
export DOCS_ROOT=/path/to/your/docs
your-docs-mcp
```

By default, the web interface is available at: **http://127.0.0.1:8123**

Open this URL in your browser to access the documentation interface.

### Features

The web interface provides:

- **Search Documentation**: Full-text search with relevance scoring and highlighted excerpts
- **Table of Contents**: Browse the complete documentation hierarchy
- **Tag-based Search**: Filter documentation by metadata tags
- **Document Viewer**: View full document content with formatting
- **Real-time Stats**: See the number of loaded documents and categories

### Configuration

You can customize the web server settings using environment variables:

```bash
# Enable/disable web server (default: true)
export MCP_DOCS_ENABLE_WEB_SERVER=true

# Web server host (default: 127.0.0.1)
export MCP_DOCS_WEB_HOST=127.0.0.1

# Web server port (default: 8123)
export MCP_DOCS_WEB_PORT=8123
```

### API Endpoints

The web interface also exposes REST API endpoints that you can use programmatically:

- `GET /api/health` - Health check and statistics
- `GET|POST /api/search` - Search documentation
- `GET|POST /api/navigate` - Navigate to specific URIs
- `GET|POST /api/toc` - Get table of contents
- `POST /api/search-by-tags` - Search by tags
- `GET|POST /api/document` - Get document content

Example API usage:

```bash
# Search for documentation
curl "http://localhost:8123/api/search?query=authentication"

# Get a specific document
curl "http://localhost:8123/api/document?uri=docs://guides/quickstart/installation"

# Get table of contents
curl "http://localhost:8123/api/toc"
```

## Usage Examples

### Ask Your AI Assistant

Once configured, you can ask your AI assistant natural language questions:

- "Show me the getting started guide"
- "List all available documentation"
- "What authentication methods are available?"
- "Show me all API endpoints for user management"
- "Search for documentation about deployment"

### Supported Document Formats

**Markdown Files** (`.md`, `.mdx`):
```markdown
---
title: Getting Started
tags: [guide, quickstart]
category: guides
order: 1
---

# Getting Started

Your documentation content here...
```

**OpenAPI Specifications** (`.yaml`, `.json`):
```yaml
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      ...
```

## Advanced Configuration

### Multi-Source Setup

Create `.mcp-docs.yaml` in your project:

```yaml
sources:
  - path: ./docs
    category: guides
    label: User Guides
    recursive: true

  - path: ./api-specs
    category: api
    label: API Reference
    format_type: openapi

cache:
  ttl: 3600
  max_memory_mb: 500

security:
  allow_hidden_files: false
  audit_logging: true
```

### Environment Variables

See `.env.example` for all available configuration options:

- `DOCS_ROOT`: Documentation root directory (required)
- `MCP_DOCS_CACHE_TTL`: Cache TTL in seconds (default: 3600)
- `MCP_DOCS_OPENAPI_SPECS`: Comma-separated OpenAPI spec paths
- `MCP_DOCS_SEARCH_LIMIT`: Maximum search results (default: 10)
- `MCP_DOCS_ENABLE_WEB_SERVER`: Enable/disable web server (default: true)
- `MCP_DOCS_WEB_HOST`: Web server host (default: 127.0.0.1)
- `MCP_DOCS_WEB_PORT`: Web server port (default: 8123)
- `LOG_LEVEL`: Logging level (default: INFO)

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/esola-thomas/Markdown-MCP
cd Markdown-MCP

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy docs_mcp

# Run linting
ruff check docs_mcp
```

### Running Tests

```bash
# Run all tests
pytest

# Run specific test categories
pytest -m unit
pytest -m integration
pytest -m contract

# Run with coverage
pytest --cov=docs_mcp --cov-report=html
```

## Architecture

```
docs_mcp/
├── models/          # Data models (Document, Category, OpenAPI entities)
├── handlers/        # MCP protocol handlers (tools, resources)
├── services/        # Business logic (markdown parsing, search, hierarchy)
├── security/        # Security validation (path validation, sanitization)
└── utils/           # Utilities (logging, helpers)
```

## Security

- **Path Validation**: All file paths are validated to prevent directory traversal attacks
- **Hidden Files**: Hidden files (starting with `.`) are excluded by default
- **Query Sanitization**: Search queries are sanitized to prevent injection attacks
- **Audit Logging**: All file access attempts are logged for security auditing

## Claude Code Plugin

This repo includes a Claude Code plugin with skills for managing documentation files.

### Install the Plugin

```bash
claude --plugin-dir /path/to/your-docs-mcp/docs-plugin
```

### Available Skills

| Skill | Description |
|-------|-------------|
| `docs-plugin/skills/doc-create` | Create new docs with proper frontmatter |
| `docs-plugin/skills/doc-validate` | Validate docs against standards |
| `docs-plugin/skills/doc-template` | Generate doc templates |
| `docs-plugin/skills/doc-search` | Search documentation content |

See [`docs-plugin/README.md`](docs-plugin/README.md) for full details.

## Contributing

Contributions are welcome! Please see the contribution guidelines for more information.

## License

MIT License - see LICENSE file for details

## Links

- [Documentation](https://github.com/esola-thomas/Markdown-MCP/tree/main/docs)
- [Issue Tracker](https://github.com/esola-thomas/Markdown-MCP/issues)
- [MCP Documentation](https://modelcontextprotocol.io)
