Docs MCP

docs-mcp

Es un servidor MCP que permite buscar y consultar de manera eficiente los documentos configurados por el usuario.

Requisitos previos

Para usar docs-mcp se necesita uv. uv es una herramienta rápida para la gestión de paquetes y proyectos de Python.

Instalación de uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv

pip install uv

Consulte la guía de instalación de uv para más detalles.

Funciones principales

• 📄 Listado de documentos - Muestra todos los documentos y sus descripciones
• 🔍 Búsqueda grep - Búsqueda rápida de texto completo con expresiones regulares
• 🧠 Búsqueda semántica - Búsqueda de similitud semántica con OpenAI Embeddings (requiere configuración)
• 📝 Obtención de documentos - Obtiene el contenido completo del documento especificado
• 📖 Compatibilidad con paginación - Visualiza documentos grandes de forma eficiente por páginas

Inicio rápido

🚀 La forma más sencilla de usarlo

Se puede usar inmediatamente en proyectos con documentación existente:

# ドキュメント管理用フォルダを作成
mkdir -p my-docs/docs
# ドキュメントファイルをdocs/に配置

Agregar a la configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs"
      }
    }
  }
}

Importante: docs-mcp siempre consulta el directorio docs/ dentro de la carpeta del proyecto.

Guía de configuración

Método 1: Usar con documentación existente

Puede hacer que sus archivos Markdown o de texto sean buscables de inmediato:

1. Cree una carpeta de proyecto
2. Coloque los documentos en el directorio docs/
3. Actualice la configuración de Claude Desktop

✅ Ventaja: No requiere línea de comandos, se puede usar de inmediato
❌ Desventaja: No se pueden usar las herramientas de importación

Método 2: Usar las herramientas de importación

Para incorporar documentación desde GitHub o sitios web:

# ドキュメント管理プロジェクトをセットアップ
uv init my-docs
cd my-docs
uv add docs-mcp

# GitHubからドキュメントをインポート
uv run docs-mcp-import-github https://github.com/owner/repo

# 特定のディレクトリだけインポート
uv run docs-mcp-import-github https://github.com/owner/repo/tree/main/docs -o project-docs

✅ Ventaja: Permite incorporar documentación externa fácilmente
❌ Desventaja: Requiere la configuración de uv

Funciones avanzadas

🧠 Activar la búsqueda semántica

Puede agregar búsqueda semántica con OpenAI Embeddings:

# 1. OpenAI APIキーを設定
export OPENAI_API_KEY="sk-..."

# 2. メタデータを生成（プロジェクトディレクトリで実行）
uv run docs-mcp-generate-metadata

Agregue la clave de API en la configuración de Claude Desktop:

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-..."  // セマンティック検索が有効になる
      }
    }
  }
}

Opciones de configuración detalladas

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-...",
        "DOCS_FOLDERS": "api,guides,examples",  // 特定のフォルダのみ読み込み
        "DOCS_FILE_EXTENSIONS": ".md,.mdx,.txt,.py",  // 対象ファイル拡張子を制限
        "DOCS_MAX_CHARS_PER_PAGE": "5000",  // 1ページあたりの最大文字数
        "DOCS_LARGE_FILE_THRESHOLD": "10000"  // 自動ページネーション閾値（文字数）
      }
    }
  }
}

Herramientas disponibles

Herramientas MCP (usadas dentro de Claude)

• list_docs - Muestra la lista de documentos
• get_doc - Obtiene el contenido de un documento (compatible con paginación)
• grep_docs - Búsqueda con expresiones regulares
• semantic_search - Búsqueda de similitud semántica (requiere clave API de OpenAI)

📖 Cómo usar la función de paginación

En documentos grandes (más de 15 000 caracteres), se muestra automáticamente la primera página y se recomienda usar la paginación:

# 基本的な使い方（従来通り）
get_doc("path/to/document.md")  # 小さなファイルは全文表示、大きなファイルは自動的に1ページ目

# ページネーション使用
get_doc("path/to/document.md", page=1)  # 1ページ目（デフォルト10,000文字まで）
get_doc("path/to/document.md", page=2)  # 2ページ目
get_doc("path/to/document.md", page=3)  # 3ページ目

Ejemplo de salida con paginación:

📄 Document: pytest/reference/plugin_list.rst
📖 Page 2/5 (chars 10,001-20,000/45,123)
📏 Lines 285-570/1,324 | Max chars per page: 10,000
⚠️  Large document auto-paginated. To see other pages:
💡 get_doc('pytest/reference/plugin_list.rst', page=3)  # Next page
💡 get_doc('pytest/reference/plugin_list.rst', page=5)  # Last page
────────────────────────────────────────────────────────────

[ドキュメントの内容]

Herramientas de línea de comandos (para gestión de documentos)

• docs-mcp-import-url - Importa documentos desde un sitio web
• docs-mcp-import-github - Importa desde un repositorio de GitHub
• docs-mcp-generate-metadata - Genera metadatos para búsqueda semántica

Entorno requerido

• uv - Herramienta de gestión de entornos y paquetes de Python (se ejecuta con el comando uvx)
• Python 3.12 o superior (uv lo gestiona automáticamente)
• Clave API de OpenAI (solo si se usa búsqueda semántica)

Configuración detallada

Variables de entorno

Formatos de archivo compatibles

Ejemplo de estructura de directorios

my-docs/
└── docs/
    ├── api/
    │   └── reference.md
    ├── guides/
    │   └── quickstart.md
    └── examples/
        └── sample.py

Información para desarrolladores

Desarrollo desde el código fuente

git clone https://github.com/herring101/docs-mcp.git
cd docs-mcp
uv sync

# テスト
uv run pytest tests/

# ビルド
uv build

Detalles de las herramientas de línea de comandos

docs-mcp-import-url https://example.com/docs --output-dir imported

# リポジトリ全体をインポート
docs-mcp-import-github https://github.com/owner/repo

# 特定のパスのみインポート（docs/importedに保存される）
docs-mcp-import-github https://github.com/owner/repo/tree/main/docs --output-dir imported

# masterブランチのリポジトリも自動検出
docs-mcp-import-github https://github.com/Cysharp/UniTask

export OPENAI_API_KEY="your-key"
docs-mcp-generate-metadata

Seguridad

• Las claves de API se gestionan mediante variables de entorno
• Se restringe el acceso con DOCS_FOLDERS y DOCS_FILE_EXTENSIONS
• El único acceso a redes externas es la API de OpenAI

Solución de problemas

Licencia

Licencia MIT - LICENSE

Contribuciones

Consulte CONTRIBUTING.md.