refdocs

refdocs

refdocs は、ドキュメントに関する質問に答え、ウェブページをエージェントが実際に読める形式に変換します。検索では、質問の根拠となる情報やコードスニペットを見つけるため、公開されている技術ドキュメントと GitHub を横断して検索します。また、任意の URL を取得し、生の HTML ではなく、整形された Markdown として返します。

これは、コマンドラインツールと、エージェントに同じ 2 つの操作をツールとして提供する stdio MCP サーバーという、2 つの使い方ができる小さなプログラムです。

設定

どちらの操作にも Ref API キーが必要です。

export REF_API_KEY="your-key-here"

検索エンドポイントのデフォルトは https://api.ref.tools です。別のデプロイ先を指定する場合は、REF_API_BASE_URL で上書きしてください。リクエストを行う前にキーが確認されます。キーが設定されていない場合、REF_API_KEY の名前を示すエラーが発生します。

インストール

npx @reneturcios/refdocs search "How do I stream a response with fetch?"

または、コンテナーイメージを実行します。

docker run -i -e REF_API_KEY ghcr.io/cloudcorprecords/refdocs

コンテナーはデフォルトで MCP サーバーを起動します（下記を参照）。CLI として使用するには、CLI 引数を渡してください。

CLI

# Search the documentation
refdocs search "How do I use the cache API in Next.js?"
refdocs search "What does this error mean?" --json

# Read a page as markdown
refdocs read https://example.test/some/guide
refdocs read https://example.test/some/guide --json

# Check the configuration without making a request
refdocs check

refdocs --version

終了コード：成功時は 0、検索に失敗した場合または設定が整っていない場合（問題の内容を示すエラーが表示されます）は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

1 つの実行ファイルで、どちらの使い方にも対応します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/refdocs mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "refdocs": {
      "command": "npx",
      "args": ["-y", "@reneturcios/refdocs", "mcp"],
      "env": {
        "REF_API_KEY": "your-key-here"
      }
    }
  }
}

ツール

ツール	入力	返される内容
ref_search_documentation	query（文字列、必須）— 検索する文章または質問	公開されているドキュメントと GitHub からの一致する検索結果。それぞれ、タイトル、URL、上流が提供している場合はコンテンツまたはスニペットが含まれます。
ref_read_url	url（文字列、必須）— 読み込むウェブページの URL	Markdown に変換されたページの内容です。見出し、リンク、リスト、強調、コードブロックは Markdown 形式で保持され、スクリプト、スタイル、その他のコンテンツではないマークアップは削除されます。

検索レスポンスは寛容に解析されます。単独の配列、results リスト、documents リストのいずれも受け付けます。プレーンテキストの URL を読み込むと、テキストは変更されずに返されます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

テストはすべて偽の fetch 関数を使って実行され、実際の API 呼び出しは行われません。

ライセンス

MIT — LICENSE を参照してください。