Knowledge MCP

🚀 知識MCPサーバ

AIアシスタントに対して集中的な知識管理を提供する、本番環境で使用可能なモデルコンテキストプロトコル（MCP）サーバです。プロジェクト固有のドキュメント、検索可能な知識ベース、統合されたTODO管理、およびセッション間で永続的なAIメモリを実現するGitベースのバージョン管理機能を備えています。

🚀 クイックスタート

このサーバは、AIアシスタントに対して集中的な知識管理を提供します。以下のセクションでは、インストール方法、使用方法、およびその他の詳細について説明します。

✨ 主な機能

• 📝 プロジェクト知識管理：プロジェクトの指示書やドキュメントを集中的に保管します。
• 🔍 高度な検索：すべての知識ドキュメントに対して全文検索を行い、文脈に沿った結果を返します。
• 📋 TODOシステム：Markdownをサポートしたタスク管理機能と進捗追跡機能が組み込まれています。
• 🔐 セキュリティ重視：包括的な入力検証、パスサニタイズ、および抽象化境界を備えています。
• ⚡ 高性能：高度なファイルロックを使用して、並行操作に最適化されています。
• 📊 リクエストトレーシング：デバッグや監視のために一意のトレースIDを提供します。
• 🔄 Git統合：説明的なコミットメッセージを持つ自動バージョン管理機能があります。
• 🧪 実戦検証済み：すべての機能とエッジケースをカバーする133の包括的なテストがあります。

📦 インストール

NPM（推奨）

npm install -g @spothlynx/knowledge-mcp

ソースからのインストール

git clone https://github.com/sven-borkert/knowledge-mcp.git
cd knowledge-mcp
pnpm install
pnpm run build
npm link

💻 使用例

基本的な使用法

MCPクライアント設定

MCPクライアント設定に追加します。

{
  "mcpServers": {
    "knowledge": {
      "command": "knowledge-mcp",
      "args": []
    }
  }
}

Claudeデスクトップ設定

~/Library/Application Support/Claude/claude_desktop_config.jsonに追加します。

{
  "mcpServers": {
    "knowledge": {
      "command": "knowledge-mcp"
    }
  }
}

直接実行

# MCPサーバを起動します
knowledge-mcp

# 自動リロード機能付きの開発モード
pnpm run dev

高度な使用法

AIアシスタント設定

包括的な使用方法については、の内容をグローバル指示ファイル（例：~/.claude/CLAUDE.md）にコピーしてください。これにより、Claude Codeはすべてのプロジェクト知識管理に対してKnowledge MCPを自動的に使用するようになります。

知識は以下のように整理されます。

~/.knowledge-mcp/
├── index.json                 # プロジェクト名のマッピング
├── activity.log              # リクエストログ（gitignored）
└── projects/
    └── {project-slug}/       # git/ディレクトリから自動検出
        ├── main.md           # プロジェクトの指示書
        ├── knowledge/        # 知識ドキュメント
        │   ├── api-guide.md
        │   └── architecture.md
        └── TODO/             # TODOリスト
            └── 1/            # TODO #1
                ├── index.md  # TODOメタデータ
                └── tasks/    # 個々のタスクファイル

📚 ドキュメント

⚠️ 重要な制約事項

• プロジェクトIDは、gitリポジトリまたは現在のディレクトリ名から自動検出されます。
• すべてのパスはサニタイズされ、../や絶対パスは使用できません。
• キーワードは英数字+ドット、アンダースコア、ハイフンでなければなりません。
• ドキュメントあたり最大50章までです。
• 知識ファイルには.mdの拡張子が必要です。
• セクションヘッダーには##プレフィックスが必要です（例："## 設定"）。
• すべての変更は説明的なメッセージで自動コミットされます。
• ストレージは、gitリモートが設定されている場合、origin/mainと同期されます。

🔍 エラーコード

一般的なエラーとその意味は以下の通りです。

各エラーには、デバッグ用のtraceIdが含まれています。

📦 クライアント固有の設定

Claude Code

# グローバルスコープ（すべてのプロジェクト） - 常に最新バージョンを使用することを保証します
claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

# 現在のプロジェクトのみ
claude mcp add --scope project knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

# 開発用（ローカルビルドを使用）
claude mcp add knowledge-mcp node "$(pwd)/dist/knowledge-mcp/index.js"

Claudeデスクトップ

~/Library/Application Support/Claude/claude_desktop_config.jsonに追加します。

{
  "mcpServers": {
    "knowledge": {
      "command": "npx",
      "args": ["-y", "@spothlynx/knowledge-mcp@latest"]
    }
  }
}

一般的なMCP設定

他のMCP互換クライアントの場合：

{
  "mcpServers": {
    "knowledge-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@spothlynx/knowledge-mcp@latest"],
      "env": {}
    }
  }
}

🔄 バージョン管理

@latestと-yフラグを使用する理由

• -yフラグ：npxのインストールプロンプトをユーザーの操作なしで自動的に承認します。
• @latestタグ：npxに最新バージョンを取得するよう強制し、キャッシュされたバージョンを使用しないようにします。

重要：NPXはパッケージを無期限にキャッシュします。@latestを使用しない場合、古いバージョンが実行される可能性があります。

最新バージョンへの更新

# 最新バージョンを確実に使用するために削除して再追加します
claude mcp remove knowledge-mcp
claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

設定の優先順位

ほとんどのMCPクライアントは、複数の設定レベルをサポートしています。

1. ユーザーレベル（グローバル）：すべてのプロジェクトに適用されます。
2. プロジェクトレベル：現在のプロジェクトのみに適用されます。
3. 設定ファイル：手動での設定ファイルです。

上位レベルの設定は、通常、下位レベルの設定を上書きします。

🛡️ 環境設定

環境変数

• KNOWLEDGE_MCP_HOME：ストレージディレクトリ（デフォルト：~/.knowledge-mcp）
• KNOWLEDGE_MCP_LOG_LEVEL：ログレベル：ERROR、WARN、INFO、DEBUG（デフォルト：INFO）

自動プロジェクト識別

Knowledge MCPは、以下に基づいてプロジェクトを自動的に識別します。

• Gitリポジトリ：gitリモートURLからリポジトリ名を使用します。
• 非Gitディレクトリ：現在のディレクトリ名を使用します。

例：/path/to/my-awesome-project/.git → プロジェクトID = "my-awesome-project"

ストレージ構造

~/.knowledge-mcp/
├── .git/                      # Gitリポジトリ（自動初期化）
├── index.json                 # プロジェクト名のマッピング
├── activity.log              # リクエストアクティビティログ（gitignored）
└── projects/
    └── my-app/
        ├── main.md            # プロジェクトの指示書（集中管理、リポジトリ内にはない）
        ├── knowledge/
        │   ├── api-guide.md   # 構造化された知識ドキュメント
        │   └── architecture.md
        └── TODO/              # プロジェクトのTODOリスト
            ├── 1/             # 最初のTODOリスト
            │   ├── index.md   # TODOメタデータ
            │   └── tasks/     # 個々のタスクファイル
            └── 2/             # 2番目のTODOリスト

Gitリモート設定（推奨）

自動クラウドバックアップを有効にします。

# 1. GitHub/GitLabでリポジトリを作成します
# 2. リモートを設定します
cd ~/.knowledge-mcp
git remote add origin https://github.com/yourusername/knowledge-mcp-backup.git
git push -u origin main

# 3. 認証を設定します（SSHを推奨）
git remote set-url origin git@github.com:yourusername/knowledge-mcp-backup.git

⚠️ 重要：起動時に、Knowledge MCPはorigin/mainからプルし、ローカルの変更を上書きします。

🔍 APIリファレンス

コアツール

プロジェクト管理

• get_project_main(project_id) - プロジェクトの主要な指示書を取得します。
• update_project_main(project_id, content) - プロジェクトの指示書を更新します。
• update_project_section(project_id, section_header, new_content) - 特定のセクションを更新します。
• add_project_section(project_id, section_header, content, position?, reference_header?) - 新しいセクションを追加します。
• remove_project_section(project_id, section_header) - セクションを削除します。
• delete_project(project_id) - プロジェクト全体を削除します。

知識ドキュメント

• create_knowledge_file(project_id, filename, title, introduction, keywords, chapters) - 構造化されたドキュメントを作成します。
• get_knowledge_file(project_id, filename) - 完全なドキュメントを取得します。
• delete_knowledge_file(project_id, filename) - ドキュメントを削除します。
• update_chapter(project_id, filename, chapter_title, new_content, new_summary?) - 章を更新します。
• add_chapter(project_id, filename, chapter_title, content, position?, reference_chapter?) - 章を追加します。
• remove_chapter(project_id, filename, chapter_title) - 章を削除します。

章の反復処理

• list_chapters(project_id, filename) - すべての章をリストします（タイトルと要約のみ）。
• get_chapter(project_id, filename, chapter_title | chapter_index) - 単一の章の内容を取得します。
• get_next_chapter(project_id, filename, current_chapter_title | current_index) - 次の章を取得します。

検索と発見

• search_knowledge(project_id, query) - すべてのドキュメントに対して全文検索を行います。

TODO管理

• list_todos(project_id) - すべてのTODOリストをリストします。
• create_todo(project_id, description, tasks?) - 新しいTODOリストを作成します。
• get_todo_tasks(project_id, todo_number) - TODOリスト内のタスクを取得します。
• add_todo_task(project_id, todo_number, title, content?) - タスクを追加します。
• complete_todo_task(project_id, todo_number, task_number) - タスクを完了としてマークします。
• get_next_todo_task(project_id, todo_number) - 次の未完了のタスクを取得します。
• remove_todo_task(project_id, todo_number, task_number) - タスクを削除します。
• delete_todo(project_id, todo_number) - TODOリスト全体を削除します。

サーバ操作

• get_server_info() - サーバのバージョンと設定を取得します。
• get_storage_status() - Gitリポジトリの状態を取得します。
• sync_storage() - Gitのコミットと同期を強制します。

リソース

サーバは、閲覧用の読み取り専用リソースを提供します。

• knowledge://projects/{project_id}/main - プロジェクトの主要な指示書
• knowledge://projects/{project_id}/files - 知識ファイルのリスト
• knowledge://projects/{project_id}/chapters/{filename} - 章のリスト

🏗️ アーキテクチャ

ストレージ構造

~/.knowledge-mcp/
├── index.json                 # プロジェクト名からディレクトリへのマッピング
├── activity.log              # リクエストアクティビティログ（gitignored）
└── projects/
    └── {project-slug}/        # スラグ化されたプロジェクトディレクトリ
        ├── main.md            # プロジェクトの主要な指示書
        ├── knowledge/         # 知識ドキュメント
        │   └── *.md           # 個々の知識ファイル
        └── TODO/              # TODOリスト
            └── {number}/      # 番号付きのTODOディレクトリ
                ├── index.md   # TODOメタデータ
                └── tasks/     # 個々のタスクファイル
                    └── *.md

セキュリティ機能

• パス検証：ディレクトリトラバーサル攻撃を防止します。
• 入力サニタイズ：Zodスキーマを使用した包括的な検証。
• 抽象化境界：内部パスはクライアントに公開されません。
• アトミック操作：ファイル操作は一時ファイル+リネームパターンを使用します。
• リクエストトレーシング：すべての操作に一意のトレースIDが付与されます。

並行性とパフォーマンス

• ファイルロック：キューベースのロックにより、競合状態を防止します。
• アトミック更新：すべてのファイル操作はアトミックです。
• 効率的な検索：結果制限付きの最適化された全文検索。
• メモリ管理：大きなドキュメントに対してもメモリ使用量を制御します。

🧪 テスト

このプロジェクトには、包括的なテストカバレッジが含まれています。

# すべてのテストを実行します
pnpm run test:all

# 特定のテストスイートを実行します
npx tsx test/suites/01-project-main.test.ts

# HTMLテストレポートを生成します
pnpm run test:all && open test-results/html/merged-results.html

テストカバレッジ

• 11の包括的なテストスイートを通じて133のテスト
• CI/CDパイプラインで100%の成功率
• 並行性、Unicode、エラー条件を含むエッジケース
• 抽象化境界と入力検証のためのセキュリティテスト
• 高負荷シナリオのためのパフォーマンステスト

🔧 開発

前提条件

• Node.js 18+
• pnpm（推奨）またはnpm
• TypeScript 5.7+

開発ワークフロー

# 依存関係をインストールします
pnpm install

# 自動リロード機能付きの開発サーバを起動します
pnpm run dev

# 本番用にビルドします
pnpm run build

# 型チェックを実行します
pnpm run type-check

# リンターを実行します
pnpm run lint

# コードをフォーマットします
pnpm run format

# すべての品質チェックを実行します
pnpm run analyze

コード品質

このプロジェクトは、高いコード品質標準を強制しています。

• TypeScript：包括的な型チェックを備えた厳格モード。
• ESLint：TypeScriptをサポートした包括的なリンティング。
• Prettier：一貫したコードフォーマット。
• 静的解析：警告ゼロポリシー。
• テストカバレッジ：すべての機能が十分にテストされています。

🐛 トラブルシューティング

一般的な問題

1. "spawn npx ENOENT" または "Connection closed"

# 最新バージョンを確実に使用するために削除して再追加します
claude mcp remove knowledge-mcp
claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

2. パーミッションエラー

# ストレージディレクトリが存在し、書き込み可能であることを確認します
mkdir -p ~/.knowledge-mcp
chmod 755 ~/.knowledge-mcp

3. NPXキャッシュの問題

# 公開バージョンを使用する場合、NPXキャッシュをクリアします
rm -rf ~/.npm/_npx

# @latestで再インストールします
claude mcp remove knowledge-mcp
claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

4. バージョンの競合

# すべての設定スコープを確認します
claude mcp list

# すべてのスコープから削除して再追加します
claude mcp remove knowledge-mcp -s global
claude mcp remove knowledge-mcp -s project
claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

ログを使用したデバッグ

# MCPログを表示します（場所はクライアントによって異なります）
# Claude Codeの場合：
ls ~/Library/Caches/claude-cli-nodejs/*/mcp-logs-knowledge-mcp/

# トレースID付きのアクティビティログを表示します
tail -f ~/.knowledge-mcp/activity.log

# Gitリポジトリの状態を確認します
cd ~/.knowledge-mcp && git status

エラーコード

Knowledge MCPは、デバッグ用の標準化されたエラーコードを使用しています。

各エラーには、デバッグ用の一意のtraceIdが含まれています。grep "traceId" ~/.knowledge-mcp/activity.logを使用してログを検索してください。

インストールの検証

# Knowledge MCPが適切に設定されていることを確認します
claude mcp list | grep knowledge-mcp

# 基本機能をテストします（Claude Codeを使用する場合）
# サーバ情報を返すはずです
/mcp knowledge get_server_info

# ストレージディレクトリを確認します
ls -la ~/.knowledge-mcp/

パフォーマンスの問題

パフォーマンスが低下している場合：

1. 大規模な知識ベース：大きなドキュメントを分割することを検討してください。
2. Gitリポジトリのサイズ：古いプロジェクトをアーカイブするか、浅いクローンを使用してください。
3. 並行操作：ファイルロックにより安全性が保証されますが、大量の操作では速度が低下する可能性があります。
4. 検索パフォーマンス：広範なクエリではなく、特定のキーワードを使用してください。

詳細なデバッグ情報については、エラーハンドリングガイドを参照してください。

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 変更を加え、テストを追加します。
4. すべてのテストが通過することを確認します：pnpm run test:all
5. 品質チェックを実行します：pnpm run analyze
6. 変更をコミットします：git commit -m 'Add amazing feature'
7. ブランチにプッシュします：git push origin feature/amazing-feature
8. プルリクエストを開きます。

開発標準

• すべての新機能には包括的なテストが必要です。
• コードはすべての静的解析チェックに合格しなければなりません。
• APIの変更に対しては、ドキュメントを更新する必要があります。
• セキュリティ上の考慮事項を対処する必要があります。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• モデルコンテキストプロトコル：優れたMCP仕様に感謝します。
• TypeScriptコミュニティ：優れたツールとエコシステムに感謝します。
• コントリビューター：このプロジェクトをより良くするために貢献してくれた皆さんに感謝します。

📞 サポート

• 問題：GitHub Issues
• ドキュメント：技術仕様
• MCPプロトコル：公式ドキュメント

TypeScriptとモデルコンテキストプロトコルを使用して❤️ で構築されました