MCP 服务器

Docs-MCP

An MCP server that allows users to efficiently search and reference user-configured documents through document listing, grep searching, semantic searching with OpenAI Embeddings, and full document retrieval.

README

docs-mcp

ユーザーが設定したドキュメントを効率的に検索・参照できるMCPサーバーです。

主な機能

📄 ドキュメント一覧表示 - すべてのドキュメントとその説明を一覧表示
🔍 grep検索 - 正規表現を使った高速な全文検索
🧠 セマンティック検索 - OpenAI Embeddingsを使った意味的な類似検索
📝 ドキュメント取得 - 指定したドキュメントの全内容を取得

必要な環境

uv （install方法はこちら）
OpenAI APIキー（セマンティック検索を使用する場合）

インストール

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

セットアップ

1. 環境変数を設定

cp .env.example .env
# .envファイルを編集してOpenAI APIキーを設定

2. ドキュメントを配置

docs/ディレクトリにドキュメントを配置します。デフォルトでは、以下の拡張子のファイルが読み込まれます：

ドキュメント系: .md, .mdx, .txt, .rst, .asciidoc, .org
設定・データ系: .json, .yaml, .yml, .toml, .ini, .cfg, .conf, .xml, .csv
プログラミング言語: .py, .js, .jsx, .ts, .tsx, .java, .cpp, .c, .h, .go, .rs, .rb, .php など
スクリプト: .sh, .bash, .zsh, .ps1, .bat
Web系: .html, .css, .scss, .vue, .svelte
その他: .sql, .graphql, .proto, .ipynb, .dockerfile, .gitignore など

例（docs以下のフォルダ名はなんでもOKです。）

docs-mcp/
└── docs/
    ├── project1/
    │   ├── README.md
    │   ├── main.py
    │   └── config.yaml
    ├── project2/
    │   ├── index.js
    │   ├── styles.css
    │   └── package.json
    └── project3/
        ├── api.graphql
        └── docker-compose.yml

3. メタデータを生成（推奨）

uv run python scripts/generate_metadata.py

これにより以下のファイルが生成されます：

docs_metadata.json - 各ドキュメントの1行説明
docs_embeddings.json - セマンティック検索用のベクトルデータ

注意: このステップをスキップした場合：

list_docsコマンドはファイルパスのみを表示します（説明文なし）
semantic_searchコマンドは使用できません

新しいドキュメントを追加した場合も同じコマンドを実行してください。

MCPの設定json例

基本設定（すべてのドキュメントを読み込む）

{
    "mcpServers": {
        "docs-mcp": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "{path/to}/docs-mcp/src",
                "docs_mcp.py"
            ],
            "env": {
                "OPENAI_API_KEY": "your-openai-api-key"
            }
        }
    }
}

フォルダを指定して読み込む

環境変数DOCS_FOLDERSを使用して、特定のフォルダのみを読み込むことができます：

{
    "mcpServers": {
        "docs-mcp-project1": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "{path/to}/docs-mcp/src",
                "docs_mcp.py"
            ],
            "env": {
                "OPENAI_API_KEY": "your-openai-api-key",
                "DOCS_FOLDERS": "docs1,docs3"  // docs1とdocs3のみを読み込む
            }
        },
        "docs-mcp-project2": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "{path/to}/docs-mcp/src",
                "docs_mcp.py"
            ],
            "env": {
                "OPENAI_API_KEY": "your-openai-api-key",
                "DOCS_FOLDERS": "docs2"  // docs2のみを読み込む
            }
        }
    }
}

複数のプロジェクトを管理する場合、異なるサーバー名で複数の設定を作成できます。

カスタムファイル拡張子の設定

デフォルトで多くのファイル形式に対応していますが、特定の拡張子のみを対象にしたい場合は、環境変数DOCS_FILE_EXTENSIONSで指定できます：

{
    "mcpServers": {
        "docs-mcp-custom": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "{path/to}/docs-mcp/src",
                "docs_mcp.py"
            ],
            "env": {
                "OPENAI_API_KEY": "your-openai-api-key",
                "DOCS_FILE_EXTENSIONS": ".md,.mdx,.py,.js"  // 特定の拡張子のみ
            }
        }
    }
}

拡張子はカンマ区切りで指定し、ドット（.）は省略可能です。この設定はgenerate_metadata.pyスクリプトでも同様に機能します。

テスト

テストを実行するには：

uv run pytest tests/

スクリプト

URLからドキュメントをインポート

WebサイトのドキュメントをMarkdown形式で高速にインポートできます。並列ダウンロード機能により、大量のページも効率的に取得可能です。

uv run python scripts/url_import.py https://example.com/docs

主な特徴:

🚀 並列ダウンロード（デフォルト10並列）で高速化
📊 プログレスバーでダウンロード・保存状況を可視化
🌏 日本語URLを適切にデコードしてファイル名に変換
🌲 URLのパス構造を維持したディレクトリツリーで保存

オプション:

--output-dir, -o: 出力先ディレクトリ（デフォルト: ドメイン名）
--depth, -d: クロールの深さ（デフォルト: 2）
--include-pattern, -i: 含めるURLパターン（正規表現、複数指定可）
--exclude-pattern, -e: 除外するURLパターン（正規表現、複数指定可）
--concurrent, -c: 同時ダウンロード数（デフォルト: 10）
--timeout: タイムアウト（秒、デフォルト: 30）
--rate-limit: レート制限（秒、デフォルト: 0.1）

使用例:

# 基本的な使用
uv run python scripts/url_import.py https://mcp-jp.apidog.io/

# 特定のパスのみを深さ3でインポート
uv run python scripts/url_import.py https://docs.example.com \
    --depth 3 \
    --include-pattern "/api/.*" \
    --exclude-pattern ".*/deprecated/.*"

# 同時接続数を増やして高速化（サーバーに優しく）
uv run python scripts/url_import.py https://docs.example.com \
    --concurrent 20 \
    --rate-limit 0.05

インポート後はgenerate_metadata.pyを実行してメタデータを更新してください。

GitHubリポジトリからインポート

Gitのsparse-checkoutを使用して、GitHubリポジトリの特定フォルダをローカルに取得できます。

uv run python scripts/github_import.py https://github.com/owner/repo/tree/branch/path