docs-mcp-server CLAUDE.md

CLAUDE.md

This file provides guidance for AI assistants when working with code in this repository.

Project Overview

This is a professional MCP (Model Context Protocol) server that integrates Claude with Docs instances. It exposes 31 tools and 4 resources for document management, access control, version history, AI-powered features, and document content editing via Yjs (CRDT).

Key Components:

• DocsAPIClient (client.py) - Async HTTP client with retry logic and rate limiting
• DocsServer (server.py) - MCP server implementation with tool/resource handlers
• DocsConfig (config.py) - Pydantic-based configuration from environment variables
• Pydantic models (models.py) - Type-safe data models for all API entities
• YjsDocumentUtils (yjs_utils.py) - Utilities for Yjs document manipulation (v0.2.0+)

Development Commands

Setup

# Install in development mode with all dev dependencies
pip install -e ".[dev]"

# Install only test dependencies
pip install -e ".[test]"

# Setup pre-commit hooks
pre-commit install

Testing

# Run all tests
pytest

# Run with coverage report
pytest --cov=docs_mcp_server --cov-report=html

# Run specific test file
pytest tests/test_client.py -v

# Run tests in parallel
pytest -n auto

Code Quality

# Lint and format with ruff (this project uses ruff, not black/flake8)
ruff check src/ tests/
ruff format src/ tests/

# Type checking with mypy (strict mode disabled, see pyproject.toml)
mypy src/docs_mcp_server

# Security scanning
bandit -r src/
safety check

Running the Server

# Start MCP server (requires DOCS_BASE_URL and DOCS_API_TOKEN env vars)
docs-mcp-server

# Check configuration validity
docs-mcp-server --config-check

# Run with explicit config
docs-mcp-server --base-url https://docs.example.com --token your-token

# Run as Python module
python -m docs_mcp_server