oneshot-mcp

oneshot-mcp

コーディングエージェントがエディターを離れずに、レシートで検証済みのビルドパックを掲載する OneShot カタログを検索できる MCP サーバーです。ビルドの途中で、ストアフロントを確認することを覚えておく代わりに、エージェントに「これに使える検証済みパックはありますか？」と尋ねられます。

これを追加する理由（率直に言うと）

これはベンダーのカタログです。普段のワークフローの中から、OneShot が販売する有料ビルドパックと、その検証データをエージェントが検索できます。何かを購入するつもりがあるかどうかにかかわらず役立つため、追加する価値があります。search_packs と list_packs を使えば、開発中のものにレシートで検証済みのパックがあるかどうかを、「N 回中 M 回の実行に合格」といった実際の数値で明確に確認でき、宣伝文句に頼る必要はありません。get_pack では、何かを決める前に価格、返金条件、レシートに記載された正確な事実を確認できます。ただし、これは OneShot が自社製品をエージェントに紹介するものであり、独立したおすすめエンジンではないことを理解しておいてください。パックを「最良」と呼んだり、レシートで裏付けられない検証結果をでっち上げたりすることはありません。また、どの結果にも価格と返金に関する参照先が含まれます。しかし、このカタログは当社のものであり、掲載されているのはすべて当社が販売する商品です。

ツール

• search_packs({ query, limit? }) -- カタログからキーワードで検索します（技術スタック、課題、ニッチ分野）。一致したパックのタイトル、概要、価格、レシートで裏付けられる内容をそのまま示した検証状況（例："3 of 3 clean-room runs passed"、レシートがまだない場合は "unverified"）、レシートの概要、返金ポリシーの参照先、ストアフロントの URL を返します。結果に順位を付けたり、「最良」と呼んだりせず、一致した各項目を説明し、判断は呼び出し元に委ねます。
• get_pack({ slug }) -- 1 つのパックの詳細を返します。内容、アーキテクチャ上の判断に関する要点、対応規模、FAQ、検証済みの場合は正確なレシート情報（チェックごとの合否、モデル、トークン数／実行時間コスト）、価格、返金に関する参照先、購入 URL が含まれます。
• list_packs() -- カタログ全体を簡潔に返します。各パックのスラッグ、タイトル、概要、ニッチ分野、価格、検証状況と、返金ポリシーの概要が含まれます。

データソース：フォールバック付き取得（同梱カタログではありません）

選択肢は 2 つありました。実行時に packs/*/pack.yaml と receipt/receipt.json および LISTING.md を読み込む方法と、生成した catalog.json を npm パッケージに 組み込んで配布する方法です。選んだのはライブ読み込みです。まずストアフロントの /catalog.json を優先し、次にローカルのチェックアウトを使用します。

1. GET $ONESHOT_CATALOG_URL を試します（デフォルトは https://oneshotpacks.com/catalog.json、 タイムアウトは 3 秒）。パックオブジェクトの配列、または { "packs": [...] } のどちらでも受け付けます。
2. ネットワークエラー、非 2xx、JSON ではない、形式が不正など、何らかの理由で失敗した場合は、 $PACKS_DIR の下（デフォルトは ../packs。現在の作業ディレクトリを基準に解決されます。 このパッケージと packs/ がリポジトリのルートにある場合は、 storefront/lib/packs.ts 自身の規約と一致します）にある packs/*/pack.yaml、LISTING.md、receipt/receipt.json をディスクから直接読み込みます。
3. どちらのソースにもデータがない場合、list_packs／search_packs はそのことを明確に伝えます （catalog_source: "none" と説明メモを返します）。古くなった同梱データは提供しません。 このサーバーがカタログの内容を捏造することはありません。

同梱の catalog.json は採用しませんでした。パックの再検証や新規掲載があればすぐに古くなり、 ストアフロントにはすでに最新データがあるのに、データを更新するだけでサーバーを更新して npm に新しいリリースを公開する必要があるためです。ライブ読み込みに必要なのは fetch と YAML の解析だけで、ストアフロント自体のローダーと同じく低コストです。また、このサーバーを 再デプロイせずに最新データを維持できます。これは docs/03-marketing-distribution.md の レバー 2 が掲げる目的そのものです。

ストアフロントの /catalog.json エンドポイントは同僚が並行して開発中で、まだ存在しない 可能性があります。 このサーバーはエンドポイントの存在に依存しません。単純な 404 を含む あらゆる取得失敗は「まだ存在しない」として扱い、stderr に記録したうえでローカルファイルへの フォールバックに進みます。クラッシュすることはありません。/catalog.json が公開されると、 デフォルト URL のままであれば設定変更は不要で、このサーバーは次の 5 分間隔のキャッシュ更新時に 自動的に読み込みます。

長時間実行される stdio セッションでツール呼び出しのたびに再取得しないよう、レスポンスは プロセス内で 5 分間キャッシュされます。

インストール

npm ではまだ公開されていません（公開はローンチチェックリストの最初の手順です。 docs/09-launch-checklist.md を参照してください）。公開までは、チェックアウトしたこの リポジトリの絶対パスを MCP クライアントに指定してください。公開後は npx 形式に切り替えます。 形式は同じで、command／args を置き換えるだけです。

Claude Code

プロジェクトの .mcp.json に追加します（または claude mcp add を使用します）。

{
  "mcpServers": {
    "oneshot": {
      "command": "node",
      "args": ["/absolute/path/to/oneshot/oneshot-mcp/src/index.ts"]
    }
  }
}

npm で公開された後：

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

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に追加します。

{
  "mcpServers": {
    "oneshot": {
      "command": "node",
      "args": ["/absolute/path/to/oneshot/oneshot-mcp/src/index.ts"]
    }
  }
}

npm で公開された後は、上記と同じ置き換えを行います（"command": "npx", "args": ["-y", "oneshot-mcp"]）。

環境変数（任意。いずれかのクライアント設定の env ブロック、またはシェルに指定します）

変数	デフォルト	用途
ONESHOT_CATALOG_URL	https://oneshotpacks.com/catalog.json	最初に試すリモートカタログ
ONESHOT_SITE_URL	https://oneshotpacks.com	パック／購入リンクの生成に使用するベース URL
PACKS_DIR	../packs（cwd 基準）	ローカルのフォールバック用パックディレクトリ

要件

Node >= 22.6（Node 組み込みの TypeScript 型削除機能を使って .ts ソースを直接実行します。ビルド手順、バンドラー、tsc は不要です）。

開発

npm install
npm test              # node --test test/tools.test.ts
npm start             # runs the server on stdio (Ctrl-C to stop)
node src/index.ts --help

test/tools.test.ts は、fixtures/packs/ のフィクスチャデータを使って search_packs、get_pack、list_packs を直接テストします（MCP プロトコル経由ではありません。ツールのロジックである src/catalog.ts は トランスポートに依存しない単純な関数であり、src/index.ts はそれらを SDK に接続するだけです）。 カバレッジ：検索結果あり、検索結果なし、未検証パックが誠実に表示されること（合格率を捏造しない）、 不正な pack.yaml がカタログの残りをクラッシュさせずにスキップされること、そして フォールバック付き取得の一連の処理（リモート取得成功、リモート 404、リモートネットワークエラー、 リモート形式の不正、リモートエントリ単位の許容処理、TTL キャッシュ）。