mcp-library-docs
Provides AI assistants with access to design documentation across multiple code libraries, enabling discovery of existing utilities and patterns to avoid reimplementation.
README
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.
- Create
designs/INDEX.mdin 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
-
Add the MCP server to your AI coding assistant (see Setup below)
-
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:
- Auto-discovers current project: Walks up from Claude's working directory to find the nearest
designs/INDEX.md - Loads external libraries: Reads any libraries configured in
config.yaml(see Config File Location) - 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:
# 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 fromlist_librariesresponsetopic(string, required): Document name without.mdextension
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:
- Call
get_index_status(cwd)to see what needs updating - Get the
update_indexprompt for formatting guidance - Read any new .md files to understand them
- 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.
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.