mcp-docs-collector

v0.0.2

Published

6 months ago

MCP server for collecting documentation from various sources

Downloads

0High
0Medium
0Low

aramassa

mcp documentation model-context-protocol docs-collector git confluence web-scraping

mcp-docs-collector

MCPサーバーと連携して、様々なソースからドキュメントを収集し、参照可能にするnpmパッケージです。

プロジェクト概要

mcp-docs-collectorは、MCPサーバーと連携して複数のソースからドキュメントを自動収集し、AI開発者が参照可能な形で提供するツールです。設定ファイル（YAML）により、どのソースからどのようなドキュメントを収集するかを柔軟に定義できます。

機能

サポートするリソースタイプ

| リソースタイプ | 説明 | 主な用途 | |-------------|------|----------| | local | ローカルファイルシステム | プロジェクト内ドキュメント、ソースコード | | git | Gitリポジトリ | 外部リポジトリのドキュメント・コード参照 | | confluence | Confluence Wiki | 組織内ナレッジベース、設計ドキュメント | | web | Webページ・sitemap | 公開API仕様書、外部ドキュメント |

主要機能

📁 柔軟なファイル収集: glob パターンによるinclude/exclude指定
🔐 認証対応: SSH、HTTPS、PAT、環境変数による認証
🔄 自動変換: HTML→Markdown変換、本文抽出
⚙️ 環境変数サポート: 設定ファイル内での変数展開
🛠️ MCPサーバー統合: シームレスなツール登録

セットアップ

前提条件

Node.js 18+
TypeScript (npx tsx で実行可能)
Git (gitリソース使用時)

インストール

NPMパッケージとしてインストール（推奨）

# グローバルインストール（CLIとして使用）
npm install -g mcp-docs-collector

# プロジェクト内でのライブラリ使用
npm install mcp-docs-collector

開発用にリポジトリから直接使用

git clone https://github.com/Aramassa/mcp-docs-collector.git
cd mcp-docs-collector
npm install
npm run build

基本的なセットアップ

設定ファイルを作成

cp mcp_ref_docs.yaml my_config.yaml
# 設定ファイルを編集

必要に応じて環境変数ファイルを作成
```
echo "GITHUB_TOKEN=your_token" > .env
```

テスト実行

# グローバルインストール後
mcp-docs-collector --config my_config.yaml --env-file .env
   
# またはnpxで実行
npx mcp-docs-collector --config my_config.yaml --env-file .env

開発

技術スタック

言語: TypeScript
テスト: Vitest
パッケージマネージャー: npm
ビルド: TypeScript Compiler

プロジェクト構造

mcp-docs-collector/
├── src/                      # ソースコード
│   ├── index.ts             # エントリポイント
│   └── utils/               # ユーティリティ・コアロジック
│       ├── configParser.ts  # 設定ファイル解析
│       ├── localUtils.ts    # ローカルファイル操作
│       ├── resourceTypes.ts # リソース型定義
│       ├── toolTypes.ts     # MCPツール型定義
│       ├── logger.ts        # ロギング基盤
│       └── loader/          # リソースローダー実装
│           ├── localResourceLoader.ts
│           ├── gitResourceLoader.ts
│           ├── confluenceResourceLoader.ts
│           └── webResourceLoader.ts
├── test/                    # テストコード
│   ├── fixtures/           # テスト用固定データ
│   └── *.test.ts           # 各種テストファイル
├── docs/                   # 詳細ドキュメント
├── change_plans/           # 設計変更履歴
└── mcp_ref_docs.yaml       # 設定ファイル例

詳細な解説はコード構造ドキュメントを参照してください。

開発コマンド

# 依存関係インストール
npm ci

# ビルド
npm run build

# テスト実行
npm test

# テストUI
npm run test:ui

# リンティング・フォーマット
npm run lint        # ESLint による静的解析
npm run lint:fix    # ESLint による自動修正
npm run format      # Prettier による整形
npm run format:check # Prettier による整形チェック

CI/CD

GitHub Actionsを使用したCI/CDパイプラインが設定されています：

自動テスト実行: プッシュ・プルリクエスト時にテストが自動実行
マルチバージョン対応: Node.js 18.x, 20.x での動作確認
ビルド検証: TypeScriptコンパイルの確認

CI/CD環境での詳細な設定方法は環境変数ドキュメントを参照してください。

テスト方針

テストフレームワーク: Vitest
カバレッジ目標: 80%以上
テストデータ: test/fixtures/ に事前配置
モック: axios、logger等は適切にモック化

テスト用fixtureファイルは動的生成を避け、test/fixtures/に事前配置してテストの安定性を保っています。

コーディングスタイル

ESM形式、TypeScript厳格モード
ESLint + @typescript-eslint + Prettier による静的解析・コード整形
Airbnb TypeScript ルールベースの設定
クラスベース設計、単一責任原則
環境差分は設定ファイルで管理
YAMLテンプレートは複数行+インデント整形で可読性優先

コード品質の確保とスタイル統一のため、コミット前に以下を実行してください：

npm run lint:fix  # ESLintエラーの自動修正
npm run format    # Prettierによる整形
npm test          # テスト実行

使い方

mcp-docs-collectorは、NPMパッケージとしてCLIツールとライブラリの両方として利用できます。

CLIとしての使用（グローバルインストール後）

# 設定ファイルのみ指定
mcp-docs-collector --config mcp_ref_docs.yaml

# 環境変数ファイルも使用
mcp-docs-collector --config mcp_ref_docs.yaml --env-file .env

# 複数ファイルを組み合わせ
mcp-docs-collector --config config1.yaml --config config2.yaml --env-file .env.local --env-file .env.prod

# Git URLを直接指定
mcp-docs-collector --git-url "https://github.com/user/repo|main|docs/"

# ヘルプの表示
mcp-docs-collector --help

# バージョン確認
mcp-docs-collector --version

npxを使った実行（ローカルインストール時）

# プロジェクト内でnpxを使用
npx mcp-docs-collector --config mcp_ref_docs.yaml --env-file .env

プログラマブル使用（ライブラリとして）

import { ConfigLoader, GitResourceLoader } from 'mcp-docs-collector';

const configLoader = new ConfigLoader(['config.yaml'], ['.env']);
const config = await configLoader.load();

// 個別のローダーを使用
const gitLoader = new GitResourceLoader({
  type: 'git',
  url: 'https://github.com/user/repo',
  branch: 'main',
  path: 'docs/',
  group: 'external-docs',
  resources: [{ name: 'documentation' }]
});

開発環境での実行（リポジトリから直接）

# TypeScriptを直接実行
npx tsx src/index.ts --config mcp_ref_docs.yaml

# ビルド後に実行
npm run build
node dist/cli.js --config mcp_ref_docs.yaml

コマンドラインオプション

| オプション | 説明 | 例 | |-----------|------|-----| | --config | 設定ファイルパス（複数指定可） | --config config.yaml | | --env-file | 環境変数ファイルパス（複数指定可） | --env-file .env | | --git-url | Git URLリソース直接指定（複数指定可） | --git-url "repo\|branch\|path" |

設定ファイル

基本構造

# 環境変数をprocess.envに反映（任意）
export_envs:
  - GITHUB_TOKEN
  - API_KEY

# リソース定義
docs:
  - type: local
    path: ./docs
    group: project-docs  # 任意
    resources:
      - name: markdown
        description: "プロジェクトドキュメント"
        includes: ["**/*.md"]
        excludes: ["node_modules/**"]

  - type: git
    repoUrl: [email protected]:example/repo.git
    group: external-docs
    resources:
      - name: api-docs
        includes: ["docs/**/*.md"]

  - type: confluence
    baseUrl: https://company.atlassian.net/wiki
    apiKey: ${CONFLUENCE_PAT}
    userEmail: ${USER_EMAIL}
    resources:
      - name: design-docs
        spaceKey: DESIGN

  - type: web
    userAgent: "Custom Agent"
    timeout: 30000
    resources:
      - name: api-reference
        urls:
          - https://api.example.com/docs
        sitemaps:
          - url: https://example.com/sitemap.xml
            include: ["^https://example\\.com/docs/.*"]

ツール名の制限

ツール名（group名とresource名の組み合わせ）には以下の制限があります：

禁止文字: スラッシュ (/) とコロン (:) は使用できません
グループ区切り: group名とresource名はアンダースコア (_) で結合されます
エラー: 無効な文字が含まれている場合、設定読み込み時にエラーが発生します

正しい例:

docs:
  - type: local
    group: project_docs  # OK: アンダースコア使用
    resources:
      - name: api_reference  # OK: 最終的に "project_docs_api_reference" になる

間違った例:

docs:
  - type: local
    group: project/docs  # NG: スラッシュは禁止
    resources:
      - name: api:reference  # NG: コロンは禁止

環境変数

設定ファイル内での変数展開

設定ファイル内で ${VAR_NAME} 形式で環境変数を参照できます：

docs:
  - type: git
    repoUrl: ${REPO_URL}
    resources:
      - name: docs
        includes: ["**/*.md"]

環境変数ファイルの優先順位

複数の環境変数ファイルを指定した場合、後から指定したファイルが優先されます：

# .env.base < .env.local の順で適用
npx tsx src/index.ts --config config.yaml --env-file .env.base --env-file .env.local

主要な環境変数

| 変数名 | 用途 | 例 | |--------|------|-----| | GITHUB_TOKEN | GitHubプライベートリポジトリアクセス | ghp_xxx... | | GH_TOKEN | GitHub CLI互換トークン | ghp_xxx... | | CONFLUENCE_PAT | Confluence PAT | xxx... | | CONFLUENCE_USER_EMAIL | Confluenceユーザー | [email protected] | | LOCAL_CWD | ローカルリソースのベースディレクトリ | /path/to/project | | DEBUG | デバッグログ出力 | 1 |

詳細は環境変数ドキュメントを参照してください。

MCP Inspectorでの実行

@modelcontextprotocol/inspector を使用してリアルタイムでの動作確認やデバッグが可能です。

基本的な実行方法

# 単一設定ファイル
npx @modelcontextprotocol/inspector@latest npx tsx /path/to/mcp-docs-collector/src/index.ts --config ./mcp_ref_docs.yaml

# 複数設定ファイル + 環境変数
npx @modelcontextprotocol/inspector@latest npx tsx /path/to/mcp-docs-collector/src/index.ts \
  --config ./config1.yaml \
  --config ./config2.yaml \
  --env-file ./.env.local \
  --env-file ./.env.prod

Inspector使用時の注意事項

TypeScriptファイルを直接実行するため、tsxコマンドが必要です
設定ファイルと環境変数ファイルのパスは実行ディレクトリからの相対パスで指定
WebブラウザでInspector UIが開き、登録されたツールを確認・実行可能

デバッグログ

環境変数 DEBUG=1 を設定することで、詳細なログが ~/.mcp-docs-collector/logs/ に出力されます：

# デバッグログ有効化
DEBUG=1 npx tsx src/index.ts --config config.yaml

# ログファイル確認
tail -f ~/.mcp-docs-collector/logs/mcp-docs-collector.log

INFO レベル: 通常の処理状況
DEBUG レベル: ファイル読み込み、内部処理の詳細
ERROR レベル: エラーとスタックトレース

ドキュメント

リソースタイプ別ドキュメント

各リソースタイプの詳細な使用方法については、以下のドキュメントを参照してください：

| ドキュメント | リソースタイプ | 内容 | |-------------|-------------|------| | NPMパッケージ利用 | - | NPMパッケージとしての利用方法、CLI・ライブラリ使用例、型定義 | | ローカルリソース | type: local | ローカルファイルシステムからの収集方法、パターンマッチング、環境変数活用 | | Gitリソース | type: git, type: git-url | リポジトリからの収集、認証設定、git-url活用法 | | Confluenceリソース | type: confluence | Confluence API連携、認証設定、ページ収集方法 | | Webリソース | type: web | Webページ・sitemap収集、本文抽出、フィルタリング |

技術ドキュメント

システムの詳細仕様や拡張方法については、以下を参照してください：

| ドキュメント | 内容 | |-------------|------| | コード構造解説 | アーキテクチャ、モジュール構成、拡張方法、実装例 | | 環境変数設定 | 環境変数の使用方法、セキュリティ考慮事項、実践例 | | 設計変更履歴 | 機能追加・変更の設計経緯と議論履歴 |

クイックスタート

基本設定: README - 設定ファイル
環境変数: 環境変数設定ドキュメント
ローカルファイル: ローカルリソースドキュメント
外部リポジトリ: Gitリソースドキュメント
アーキテクチャ理解: コード構造ドキュメント

サンプル設定

mcp_ref_docs.yaml - 基本的な設定例
mcp_ref_docs_new.yaml - 新機能含む設定例

Dockerを使ったテスト実行（推奨）

docker-compose.ymlは不要です。素のDockerコマンドでテストが可能です。

docker run --rm -v $(pwd):/app -w /app -e NODE_ENV=test node:20 npm run test

Node.js公式イメージを使い、依存解決・テスト実行を1コマンドで完結できます。
macOS + zsh環境でもそのまま利用可能です。
テスト用fixtureファイルはtest/fixtures/に事前配置してください。

テスト実行（Docker + キャッシュ利用）

ローカルでDocker上のnode_modulesキャッシュを使ってテストを実行するには、以下のスクリプトを利用してください。

./scripts/test-in-docker.sh

初回実行時は依存関係のダウンロードが発生しますが、2回目以降は高速にテストが実行されます。
ホストのnode_modulesは一切参照しません。
CI（GitHub Actions）と同じ環境でテストできます。

ライセンス

ISC License - 詳細は LICENSE を参照してください。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

mcp-docs-collector

目次

プロジェクト概要

機能

サポートするリソースタイプ

主要機能

セットアップ

前提条件

インストール

NPMパッケージとしてインストール（推奨）

開発用にリポジトリから直接使用

基本的なセットアップ

開発

技術スタック

プロジェクト構造

開発コマンド

CI/CD

テスト方針

コーディングスタイル

使い方

CLIとしての使用（グローバルインストール後）

npxを使った実行（ローカルインストール時）

プログラマブル使用（ライブラリとして）

開発環境での実行（リポジトリから直接）

コマンドラインオプション

設定ファイル

基本構造

ツール名の制限

環境変数

設定ファイル内での変数展開

環境変数ファイルの優先順位

主要な環境変数

MCP Inspectorでの実行

基本的な実行方法

Inspector使用時の注意事項

デバッグログ

ドキュメント

リソースタイプ別ドキュメント

技術ドキュメント

クイックスタート

サンプル設定

Dockerを使ったテスト実行（推奨）

テスト実行（Docker + キャッシュ利用）

ライセンス