Docs MCP

docs-mcp

Este é um servidor MCP que permite pesquisar e consultar eficientemente documentos configurados pelo usuário.

Pré-requisitos

Para usar o docs-mcp, é necessário o uv. O uv é uma ferramenta rápida para gerenciamento de pacotes e projetos Python.

Instalação do 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 o guia de instalação do uv para mais detalhes.

Principais recursos

• 📄 Listagem de documentos - Lista todos os documentos e suas descrições
• 🔍 Busca grep - Busca rápida em texto completo usando expressões regulares
• 🧠 Busca semântica - Busca por similaridade semântica usando OpenAI Embeddings (requer configuração)
• 📝 Obtenção de documentos - Obtém o conteúdo completo de um documento especificado
• 📖 Suporte a paginação - Navegação eficiente de documentos grandes em páginas

Início rápido

🚀 Uso mais simples

Você pode usar imediatamente em projetos com documentos existentes:

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

Adicione à configuração do Claude Desktop (claude_desktop_config.json):

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

Importante: o docs-mcp sempre consulta o diretório docs/ dentro da pasta do projeto.

Guia de configuração

Método 1: Usar com documentos existentes

Você pode tornar pesquisáveis rapidamente arquivos Markdown ou texto que já possui:

1. Crie uma pasta de projeto
2. Coloque os documentos no diretório docs/
3. Atualize a configuração do Claude Desktop

✅ Vantagem: sem necessidade de linha de comando, pronto para uso imediato
❌ Desvantagem: a ferramenta de importação não está disponível

Método 2: Usar a ferramenta de importação

Para importar documentos do GitHub ou de sites da 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

✅ Vantagem: importa facilmente documentos externos
❌ Desvantagem: requer configuração do uv

Recursos avançados

🧠 Ativar busca semântica

Você pode adicionar busca semântica usando OpenAI Embeddings:

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

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

Adicione a chave de API na configuração do Claude Desktop:

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

Opções de configuração detalhadas

{
  "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"  // 自動ページネーション閾値（文字数）
      }
    }
  }
}

Ferramentas disponíveis

Ferramentas MCP (usadas no Claude)

• list_docs - Lista documentos
• get_doc - Obtém conteúdo de documento (com paginação)
• grep_docs - Busca com expressões regulares
• semantic_search - Busca por similaridade semântica (requer chave de API OpenAI)

📖 Como usar a paginação

Em documentos grandes (mais de 15.000 caracteres), a primeira página é exibida automaticamente e o uso de paginação é recomendado:

# 基本的な使い方（従来通り）
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ページ目

Exemplo de saída com paginação:

📄 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
────────────────────────────────────────────────────────────

[ドキュメントの内容]

Ferramentas de linha de comando (para gerenciamento de documentos)

• docs-mcp-import-url - Importa documentos de sites da web
• docs-mcp-import-github - Importa de repositórios GitHub
• docs-mcp-generate-metadata - Gera metadados para busca semântica

Ambiente necessário

• uv - Ferramenta de gerenciamento de ambiente e pacotes Python (executada com o comando uvx)
• Python 3.12 ou superior (gerenciado automaticamente pelo uv)
• Chave de API OpenAI (apenas se usar busca semântica)

Configuração detalhada

Variáveis de ambiente

Formatos de arquivo suportados

Exemplo de estrutura de diretórios

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

Informações para desenvolvedores

Desenvolvimento a partir do código-fonte

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

# テスト
uv run pytest tests/

# ビルド
uv build

Detalhes das ferramentas de linha de comando

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

Segurança

• Chaves de API gerenciadas por variáveis de ambiente
• Acesso restrito por DOCS_FOLDERS e DOCS_FILE_EXTENSIONS
• Acesso externo à rede apenas para a API da OpenAI

Solução de problemas

Licença

Licença MIT - LICENSE

Contribuição

Consulte CONTRIBUTING.md.