AI Documentation & Guru Knowledge MCP Server

ナレッジハブ

複数のプラットフォームにわたる組織のナレッジへ、AI アシスタントが統一的にアクセスできるModel Context Protocol（MCP）サーバーです。AI ツールと組織のナレッジリポジトリの間をつなぎ、ローカルドキュメント、Guru、Notion にまたがるドキュメントの作成、取得、管理をインテリジェントに行えます。

🚀 これは何ですか？

Knowledge Hub は、本番環境ですぐに利用できる MCP サーバーで、次の機能を提供します。

• 🧠 Guru ナレッジベースとの連携 - Guru のカードやコレクションの検索、読み取り、管理
• 📝 Notion データベースの管理 - Notion データベース内のドキュメントの作成、クエリ、更新、管理
• 🔍 高度なクエリと検索 - すべてのプラットフォームで強力なフィルタリング、並べ替え、検索機能を提供
• 🛠️ コンテンツの作成と管理 - 適切なメタデータとコードブロックの検証を行いながら、Markdown を Notion ページに変換
• 🔄 双方向同期 - Notion ページを Markdown 形式にエクスポート
• 🏗️ 開発モードと本番モード - 環境に応じて柔軟にデプロイ可能

🏗️ アーキテクチャ

TypeScript/Node.js（≥20.0.0）、MCP SDK v1.12.0、型安全性のための Zod 検証を使用して構築されています。関心事を分離した、すっきりとしたモジュール式のアーキテクチャを採用しています。

src/
├── index.ts              # Main MCP server entry point
├── server.ts             # Server configuration and tool registration
├── services/             # API services (Notion, Guru)
├── tools/                # MCP tool implementations
├── types/                # TypeScript type definitions
└── utils/                # Conversion utilities and helpers

🛠️ 利用可能なツール（合計 9 個）

🧠 Guru ナレッジベース（3 個のツール）

• guru-list-cards - 高度なクエリで Guru カードを検索、フィルタリング
• guru-read-card - 書式を保持してカードの内容全体を読み取り
• guru-get-card-attachments - カードの添付ファイルを一覧表示、ダウンロード

📝 Notion データベースの管理（5 個のツール）

• list-database-pages - カテゴリー、タグ、ステータスによるフィルタリングが可能な高度なクエリと検索
• create-page-from-markdown - メタデータとコードブロックの検証を行いながら、Markdown からページを作成
• update-page - 既存のページを更新（コンテンツやメタデータ、またはその両方）
• archive-page - ページをゴミ箱に移動してアーカイブ
• export-page-to-markdown - ページを整形された Markdown 形式にエクスポート

🔧 ユーティリティ（1 個のツール）

• hello - MCP の機能を紹介するサンプルツール

⚙️ 設定とセットアップ

🚀 インストール

# Clone and install
git clone https://github.com/LaserFocused-ee/ai-docs-mcp.git
cd ai-docs-mcp/mcp_server
npm install

# Development
npm run dev

# Production build
npm run build && npm start

🔗 Claude Desktop との連携

開発用設定

{
  "mcpServers": {
    "ai-knowledge-hub-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "DEV_HOME": "/path/to/your/mcp_server",
        "GURU_TOKEN": "username:token",
        "NOTION_TOKEN": "your-notion-token",
        "NOTION_MCP_DATABASE_ID": "your-database-id"
      }
    }
  }
}

本番用設定

{
  "mcpServers": {
    "ai-knowledge-hub": {
      "command": "npx",
      "args": ["ai-knowledge-hub"],
      "env": {
        "GURU_TOKEN": "username:token",
        "NOTION_TOKEN": "your-notion-token",
        "NOTION_MCP_DATABASE_ID": "your-database-id"
      }
    }
  }
}

🔑 API 認証情報

Guru：Guru にログイン → Settings → API Access → Generate token → username:token の形式にする

Notion：Notion Integrations に移動 → インテグレーションを作成 → API キーを取得 → データベースをインテグレーションと共有 → URL からデータベース ID をコピー

📁 ドキュメント構成

ローカルドキュメントは docs/ ディレクトリに整理されています。

docs/
├── code_guidelines/
│   ├── flutter/architecture/    # Flutter architecture patterns
│   ├── react/                   # React best practices
│   ├── nestjs/                  # NestJS guidelines
│   └── git/                     # Git workflows
└── service-docs/                # API guides and references

🌟 主な機能

📄 Markdown ↔ Notion の変換

• コードブロックの検証：Notion の 2000 文字制限に照らして、コードブロックを自動検証
• インテリジェントなエラー処理：論理的な区切りを保ちながら、大きなコードブロックを分割するための具体的なガイダンスを提供
• 豊富な書式設定に対応：テーブル、リスト、見出し、リンク、コードブロックなど
• メタデータの保持：カテゴリー、タグ、説明、ステータス値

🔍 高度なクエリシステム

• マルチプラットフォーム検索：ローカルドキュメント、Guru、Notion を横断する統合検索
• スマートフィルタリング：カテゴリー、タグ、ステータス、日付でフィルタリングし、柔軟に並べ替え
• ページネーションに対応：大規模なデータセットを効率的に処理

🛠️ 開発サポート

• 環境検出：開発モードと本番モードを自動で切り替え
• ホットリロード：ファイル監視に対応した開発モード
• MCP Inspector との連携：包括的なテストツール
• 型安全性：Zod 検証を含む TypeScript のフルサポート

🧪 テストと検証

クイックテスト

# Interactive UI testing
npm run inspect

# Basic validation
npm run validate

# Comprehensive test suite
npm run test:inspector

ツール呼び出しの例

# List available documentation
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name legacy-list-docs

# Search Notion pages
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list-database-pages \
  --tool-arg search="testing" --tool-arg limit=5

# Search Guru knowledge
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name guru-list-cards \
  --tool-arg searchTerms="API documentation" --tool-arg maxResults=5

💡 使用パターン

ローカルドキュメント

legacy-list-docs()  # Discover available docs
legacy-read-doc(category="code_guidelines/flutter", name="best-practices")

Notion の管理

# Context-aware search
list-database-pages(search="testing", tags=["react"], status="published")

# Create with metadata
create-page-from-markdown(
  markdown="# API Guide\n\nDocumentation...",
  metadata={category: "api-reference", tags: ["api", "rest"]}
)

Guru のナレッジへのアクセス

guru-list-cards(searchTerms="troubleshooting", maxResults=10)
guru-read-card(cardId="card-uuid")

🚀 リリースと公開

このパッケージでは、プロフェッショナルなリリース管理のために、自動化された GitHub Actions ワークフローを使用しています。

📦 ユーザー向け

• 最新の安定版をインストールします：npx ai-knowledge-hub
• すべてのリリースを確認します：GitHub Releases
• npm のバージョンを確認します：npm Package

🛠️ コントリビューター／メンテナー向け

• リリースの自動化：安全性を検証したリリースに GitHub Actions を使用します
• バージョン管理：セマンティックバージョニング（patch／minor／major）に対応しています
• 品質保証：公開前にテストと検証を自動で実施します

📋 セットアップの完全ガイド：RELEASE_SETUP.mdで、以下の詳細な手順を確認できます。

• npm トークンと GitHub シークレットの設定
• 自動リリースワークフローの使用
• セマンティックバージョニングの理解
• よくある問題のトラブルシューティング

🔒 セキュリティと要件

• Node.js：≥20.0.0 が必要です
• 認証情報の保護：環境変数のみを使用して処理します
• ファイルアクセス：docs ディレクトリのみに制限されます
• 入力検証：すべてのパラメーターを Zod スキーマで検証します
• API のレート制限：自動で処理します

📄 ライセンス

MIT License - 詳細は package.json を参照してください。

---

Knowledge Hub は、静的なドキュメント、組織の知識、コンテンツ管理を、AI アシスタント向けのインテリジェントで検索可能なエコシステムへと変革します。統合された強力な API を通じて、コンテキストを考慮した開発ガイダンス、包括的なドキュメント管理、複数のプラットフォームにまたがる組織の集合知へのシームレスなアクセスを実現します。