mcp-library-docs

An MCP server that gives Claude access to design documentation across multiple code libraries/repositories. This enables Claude to discover existing utilities, patterns, and conventions - preventing reimplementation of existing functionality.

For tips on how I use this server as part of a broader AI-assisted development workflow, see AI Dev Workflow Tips.

Installation

pip install mcp-library-docs

Quick Start

Zero config required - just create a designs/INDEX.md in your project and the server will auto-discover it.

1. Create designs/INDEX.md in your project:

# my-project

> Brief description of what this project provides

## Modules

### utils
Helper utilities for common operations.
Key exports: `retry`, `parse_date`, `format_currency`
→ Full doc: utils.md

### api
REST API client and authentication.
Key exports: `ApiClient`, `authenticate`
→ Full doc: api.md

1. Add the MCP server to your AI coding assistant (see Setup below)

1. Claude will now discover your project's design docs when working in that directory.

Setup

Claude Code

Add the server using the CLI:

claude mcp add library-docs -- python -m mcp_library_docs

Or manually add to your MCP config (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "library-docs": {
      "command": "python",
      "args": ["-m", "mcp_library_docs"]
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):

{
  "mcpServers": {
    "library-docs": {
      "command": "python",
      "args": ["-m", "mcp_library_docs"]
    }
  }
}

Or use an absolute path to the Python interpreter if needed:

{
  "mcpServers": {
    "library-docs": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "mcp_library_docs"]
    }
  }
}

How It Works

When Claude calls list_libraries, the server:

1. Auto-discovers current project: Walks up from Claude's working directory to find the nearest designs/INDEX.md
2. Loads external libraries: Reads any libraries configured in config.yaml (see Config File Location)
3. Returns combined index: All INDEX.md contents with type tags ([current project], [library], [project])

Claude can then call get_design_doc(library, topic) to read detailed documentation.

Configuration

Configuration is optional. Without it, the server just discovers the current project.

Config File Location

The server searches for config.yaml in platform-specific locations:

| Platform | Primary Location | Fallback | |----------|-----------------|----------| | Linux | ~/.config/mcp-library-docs/ | - | | macOS | ~/.config/mcp-library-docs/ | ~/Library/Application Support/mcp-library-docs/ | | Windows | %APPDATA%\mcp-library-docs\ | ~/.config/mcp-library-docs/ |

The first existing directory is used. If none exist, the primary location is used.

Environment variable override: Set MCP_LIBRARY_DOCS_CONFIG_DIR to use a custom location:

export MCP_LIBRARY_DOCS_CONFIG_DIR=/custom/path

Config File Format

Create config.yaml in the config directory to register external libraries:

# Global defaults (all optional)
defaults:
  designs_dir: designs      # Directory name to look for (default: designs)
  index_file: INDEX.md      # Index file name (default: INDEX.md)
  cache: dynamic            # "static" or "dynamic" (default: dynamic)

# External libraries
libraries:
  # A shared utility library - Claude should import from this
  lib-utils:
    path: ~/projects/lib-utils
    type: library           # "library" = Claude can import from this

  # Another project for reference - Claude should learn patterns, not import
  other-app:
    path: ~/projects/other-app
    type: project           # "project" = inspiration/patterns only

  # Library with custom doc location
  legacy-lib:
    path: ~/projects/legacy-lib
    designs_dir: docs/design    # Override designs directory
    index_file: README.md       # Override index file name
    cache: static               # Cache on startup, don't re-read

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | path | required | Path to library root (~ is expanded) | | type | library | library (import from) or project (patterns only) | | designs_dir | designs | Directory containing design docs | | index_file | INDEX.md | Name of the index file | | cache | dynamic | static (read once) or dynamic (read each time) |

Library Types

The type affects how Claude interprets the documentation:

• library → [library] tag → "I can/should import and reuse this code"
• project → [project] tag → "Learn patterns, but don't import from here"
• Current project → [current project] tag → "I'm working here, prioritize this"

MCP Tools

list_libraries

Returns all INDEX.md contents from discovered and configured libraries.

Parameters:

• cwd (string, required): Current working directory

Example response: ```markdown

my-app [current project]

Main application

Modules

api

REST endpoints... → Full doc: api.md

---

lib-utils [library]

Shared utilities

Modules

dates

Date parsing utilities... → Full doc: dates.md ```

get_design_doc

Returns the full content of a specific design document.

Parameters:

• library (string, required): Library name from list_libraries response
• topic (string, required): Document name without .md extension

Example: get_design_doc(library="lib-utils", topic="dates")

get_index_status

Returns the status of INDEX.md compared to actual files in designs/.

Parameters:

• cwd (string, required): Current working directory

Returns: Shows which docs need adding to INDEX.md and which entries are stale.

Example: Use this before updating INDEX.md to see what needs attention.

MCP Prompts

update_index

Provides guidelines for updating INDEX.md files. Includes:

• Recommended format for entries
• Best practices (concise descriptions, key exports)
• Examples

Workflow for updating INDEX.md:

1. Call get_index_status(cwd) to see what needs updating
2. Get the update_index prompt for formatting guidance
3. Read any new .md files to understand them
4. Update INDEX.md with properly formatted entries

Writing Good Design Docs

INDEX.md Structure

# {Library Name}

> One-line description

Install: `pip install {package}` or `import from {path}`

## Modules

### {module_name}
Brief description of what this module does.
Key exports: `export1`, `export2`, `export3`
→ Full doc: {module_name}.md

Topic Doc Structure

# {Module Name}

> One-line purpose

## When to use this
- Use case 1
- Use case 2
- **Don't use for**: [common mistakes]

## Key exports

### `function_name(param: Type) -> ReturnType`
What this function does.

\```python
result = function_name(value)
\```

## Patterns and conventions
[How to use this module correctly]

CLI Options

python -m mcp_library_docs [--debug] [--config PATH]

• --debug: Enable debug logging to stderr
• --config PATH: Use custom config file path

Full Documentation

See designs/mcp-library-docs-design.md for complete design documentation.