ASTGL Knowledge

mcp-astgl-knowledge

AI アシスタントが As The Geek Learns のコンテンツを検索し、引用できる MCP サーバーです。MCP サーバー、ローカル AI、AI 自動化、ASTGL プロジェクトのドキュメントを扱います。

AI アシスタントがこのサーバーに接続すると、インデックス化された ASTGL の記事、チュートリアル、比較、ガイド、プロジェクトのドキュメントを検索できます。検索結果には、astgl.ai への出典 URL が含まれます。

要件： セマンティックツール（search_articles、get_answer、get_tutorial、compare_topics）は、クエリを実行時にローカルの Ollama でベクトル化します。nomic-embed-text が実行されている必要があります（デフォルトは http://localhost:11434）。メタデータツール（find_articles、list_tags、list_topics、get_latest）は Ollama なしで動作します。

クイックスタート

Claude Desktop

claude_desktop_config.json に追加します。

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

Claude Code

プロジェクトの .mcp.json に追加します。

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

Cursor ／汎用 MCP クライアント

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

登録ありの場合（1 日あたり 500 クエリ）

register ツールで登録して API キーを取得し、設定に追加します。

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"],
      "env": {
        "ASTGL_API_KEY": "astgl_your_api_key_here"
      }
    }
  }
}

ツール

search_articles

クエリでナレッジベースを検索します。関連度スコアと出典 URL を含む、関連度順の結果を返します。

パラメーター	型	必須	説明
query	string	はい	検索クエリ（例：「MCP サーバーの構築方法」）
limit	number	いいえ	最大結果数、1～20（デフォルト：5）
content_type	string	いいえ	種類で絞り込み：article、tutorial、faq、comparison、guide、newsletter、project

get_answer

特定の質問に対する直接的な回答を取得します。簡潔な回答になるよう、FAQ の項目を優先します。

パラメーター	型	必須	説明
question	string	はい	特定の質問（例：「MCP サーバーとは何ですか？」）
content_type	string	いいえ	コンテンツの種類で絞り込み

get_tutorial

チュートリアルやガイドのコンテンツから、手順を追った説明を取得します。

パラメーター	型	必須	説明
query	string	はい	学びたい内容（例：「Mac での Ollama のセットアップ」）

compare_topics

2 つのトピックを並べて比較します。

パラメーター	型	必須	説明
topic_a	string	はい	1 つ目のトピック
topic_b	string	はい	2 つ目のトピック

get_latest

追加された最新のコンテンツを取得します。

パラメーター	型	必須	説明
limit	number	いいえ	最大結果数、1～20（デフォルト：5）

list_topics

ナレッジベースのすべてのトピックを、コンテンツの種類やセクション見出しとともに一覧表示します。

register

メールアドレスを登録すると、1 日あたりのクエリ上限が 50 件から 500 件に増えます。

パラメーター	型	必須	説明
email	string	はい	メールアドレス

その他のツール

サーバーには合計 17 個のツールが登録されています。その他のツールは次のとおりです。

ツール	機能	主なパラメーター
find_articles	タグ、種類、タイトルのテキスト、日付範囲による構造化検索（ベクトル化なし）	tag、content_type、title、date_from、date_to
list_tags	各タグとその記事数を一覧表示	—
suggest_ideas	クエリ分析（不足しているトピック、自信度の低いクエリ）に基づくトピックの提案	days（デフォルト：7）、limit
add_idea / list_ideas / export_ideas	インデックスとともに保存されるアイデアジャーナル	title、description、status、priority、source
export_article	1 件の記事を Markdown 投稿として出力	url
export_topic_roundup	関連記事からまとめ記事を作成	topic、limit
export_qa_compilation	記事の Q&A ペアから FAQ 形式の Markdown を作成	topic、limit
generate_dashboard_data	JSON 分析スナップショットを生成（任意で data/dashboard.json に書き込み）	days（デフォルト：30）、output_file

コンテンツの種類

種類	説明
article	MCP、ローカル AI、自動化に関する情報コンテンツ
project	ASTGL プロジェクトのドキュメント
tutorial	手順を追ったハウツーガイド
comparison	トピックを並べて比較分析したコンテンツ
guide	包括的なリファレンス資料
newsletter	個人的な近況やお知らせ
faq	主に質疑応答形式のコンテンツ
concept	Wiki の概念ページ（公開されるのは許可リストに登録されたページのみ）
entity	Wiki のエンティティページ（公開されるのは許可リストに登録されたページのみ）

コンテンツが追加されると件数は変わります。最新のインデックスを確認するには、list_topics または list_tags を呼び出してください。 draft と synthesis のエントリーはメンテナーデータベースにのみ存在し、公開版からは削除されます。ツールスキーマの content_type の説明には、最初の 7 種類のみが記載されています。

レート制限

ティア	制限	利用方法
Public	50 クエリ／日	デフォルト（匿名）
Registered	500 クエリ／日	メールアドレスを使って register ツールを利用

制限は UTC の午前 0 時にリセットされます。レート制限の情報は、すべてのレスポンスに含まれます。

制限と登録はサーバープロセス自体によって管理されます。利用状況と登録情報はローカルの SQLite ファイル（パッケージと同じ場所の data/query-log.db、または ASTGL_QUERY_LOG_DB）に保存され、匿名クライアントには ~/.astgl-client-id に永続 ID が付与されます。ASTGL_API_KEY は、ローカルの登録テーブルに存在する場合にのみ登録済みとして扱われます。

動作の仕組み

ナレッジベースは、ASTGL の記事からセマンティック埋め込み（nomic-embed-text、768 次元）を使用して事前に構築されています。コンテンツはセクションおよび FAQ エントリーごとにチャンク化され、埋め込み処理された後、ベクトル類似検索用の sqlite-vec とともに SQLite データベースに保存されます。

記事の埋め込みは事前計算され、npm パッケージに同梱されるため、コンテンツの再インデックスは不要です。セマンティックツールでは、クエリは引き続き実行時に Ollama を通じて埋め込み処理されます（上記の要件を参照）。

サーバーは data/knowledge.db が存在する場合はそれを開き（メンテナーのチェックアウト）、存在しない場合は build/knowledge-public.db を開きます。npm パッケージには build/knowledge-public.db のみが同梱されます。このファイルは npm run build-public-db によって、公開対象外のすべての行を物理的に削除して生成されます（docs/adr/ を参照）。

パフォーマンス

• 一般的な応答時間：100～500ms（埋め込みの検索とベクトル検索）
• 埋め込み結果はメモリにキャッシュされます（LRU、200 エントリー）。繰り返しのクエリにはほぼ瞬時に応答します
• Ollama の呼び出しには 10 秒のタイムアウトと自動再試行が設定されています
• クエリのログ記録は非同期／バッチ処理され、応答をブロックしません
• レート制限のチェック結果は 5 秒間キャッシュされます

メンテナー向け

セットアップ

git clone https://github.com/Jmeg8r/mcp-astgl-knowledge.git
cd mcp-astgl-knowledge
npm install

スクリプト

スクリプト	説明
npm run build	TypeScript をコンパイル
npm test	テストスイートを実行（tsx 経由の node:test）
npm run dev	MCP サーバーを開発モードで実行（tsx）
npm start	コンパイル済みの MCP サーバーを実行
npm run ingest	ローカルの Markdown から knowledge.db を再構築（Ollama が必要）
npm run ingest-projects	astgl-site の projects.json からプロジェクトのドキュメントをインデックス化
npm run discover	RSS／サイトマップを確認して新しいコンテンツを検索
npm run structure	検出したコンテンツを処理（分類、埋め込み、インデックス化）
npm run pipeline	検索と構造化を一度に実行
npm run daily-report	AEO 分析レポートを生成
npm run alerts	コンテンツのギャップに関するアラートチェックを実行
npm run freshness	古くなったコンテンツとエコシステムのバージョン変更を確認
npm run publish-drift	ローカルの公開可能なコンテンツと、npm で実際に提供される内容を比較
npm run citation-test	AI による引用テストを手動で実行
npm run related	ベクトル類似度を使って記事への内部リンクを生成
npm run build-public-db	非公開の行を削除した build/knowledge-public.db を書き出す（prepack で実行）

その他のメンテナースクリプト（下書きの取り込みと照合、書き換えキュー、Wiki 同期、バックアップの整理、ダッシュボードデータ、MCPB バンドル）は package.json に記載されています。

環境変数

変数	デフォルト	説明
OLLAMA_URL	http://localhost:11434	Ollama エンドポイント（開発／再ビルド時のみ）
EMBED_MODEL	nomic-embed-text	埋め込みモデル
DISCORD_WEBHOOK_URL	—	レポート／アラート用の Discord Webhook
ASTGL_API_KEY	—	登録済みティアの API キー
ASTGL_ARTICLES_DIR	~/Projects/astgl-site/src/content/answers	ローカルの Markdown ソース
ASTGL_PROJECTS_JSON	~/Projects/astgl-site/src/data/projects.json	プロジェクトのデータソース
ASTGL_QUERY_LOG_DB	data/query-log.db	クエリログ、レート制限、登録情報
ASTGL_CITATION_TEST_DB	data/citation-test.db	引用テストの結果

自動ジョブ

ジョブ	スケジュール	目的
コンテンツパイプライン	6 時間ごと	新しいコンテンツの検出と構造化
日次レポート	午前 8 時	クエリ分析と健全性指標（JSON レポート）
コンテンツアラート	午前 9 時	ギャップ検出、引用ゼロの検出、競合他社のスキャン（JSON レポート）
鮮度チェック	午前 10 時	古いコンテンツとエコシステムのバージョンを追跡（JSON レポート）
下書きパイプライン	深夜 0 時	公開前の下書きをインデックス化
Wiki 同期	00:30	タグ付けされた Wiki ページをインデックスに増分同期
下書き調整	午前 2 時	ソースがなくなった下書きエントリを廃止
引用テストのリマインダー	毎週月曜日の午前 9 時	引用テストの実行を通知

スケジュールは cron/*.json で定義されています。スケジュールされたレポートジョブは、外部スケジューラーが取得して配信する JSON を出力します。レポートスクリプトを --discord 付きで実行すると、代わりに DISCORD_WEBHOOK_URL に投稿できます。パイプライン、下書き、Wiki ジョブ用の macOS launchd plist は launchd/ にあります。

アーキテクチャ

flowchart TD
    Client["MCP client<br/>(Claude, Cursor, ...)"] -->|"stdio"| Server["MCP server<br/>src/index.ts (17 tools)"]
    Server --> RL["Rate limit + query log<br/>data/query-log.db"]
    Server --> Search["src/search.ts"]
    Search -->|"embed query"| Ollama["Ollama<br/>nomic-embed-text"]
    Search -->|"sqlite-vec KNN"| KDB[("knowledge.db<br/>or knowledge-public.db")]
    Sources["astgl.ai RSS / sitemap<br/>+ local markdown"] -->|"discover, structure, ingest"| KDB
    KDB -->|"build-public-db"| Pub[("build/knowledge-public.db<br/>(shipped in npm)")]
    Jobs["Report jobs<br/>daily report, alerts, freshness"] -.->|"--discord (manual)"| Discord["Discord webhook"]

レンダリング済みの図は docs/diagrams/mcp-astgl-knowledge.architecture.svg にあります （ソース：docs/diagrams/mcp-astgl-knowledge.architecture.json）。

ライセンス

MIT