Beans 課題トラッカー用の MCP（Model Context Protocol）サーバー。AI による Beans ワークスペースとの対話のためのプログラムインターフェースと CLI インターフェースを提供します。
ドキュメント: beans-mcp.self.agency
🤖 VS Code で Beans を GitHub Copilot と完全統合してお試しください！selfagency.beans-vscode 拡張機能をインストールしてください。
npx @selfagency/beans-mcp /path/to/workspace@selfagency/beans-mcp は独自のパッケージバージョン管理を行います。Beans CLI との互換性は別途追跡されます。
起動時に、サーバーはインストールされている beans CLI のバージョンと、ハードコードされたサポート対象 Beans バージョン 0.4.2 を比較します。異なる場合は、警告を stderr に出力して起動を続行します。
--workspace-root または位置引数: ワークスペースのルートパス
--cli-path: Beans CLI へのパス
--port: MCP サーバーのポート（デフォルト: 39173）
--log-dir: ログディレクトリ
-h, --help: 使用方法を表示して終了
Related MCP server: jira-cli-mcp
ツール | 説明 |
| ワークスペースを初期化します（オプションの |
| 完了または破棄された beans をアーカイブします。 |
|
|
| 新しい bean を作成します（タイトル/タイプ + オプションの body/parent）。 |
| 1 回の呼び出しで複数の bean を作成し、オプションで共通の親の下に配置します。 |
| メタデータと本文の更新を統合（status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace）し、オプションの楽観的同時実行ヒント（ |
| 1 回の呼び出しで複数の bean を更新し、オプションでそれらを共通の親に再割り当てします。 |
| bean 内のすべての Markdown チェックリストタスクを完了としてマークします。 |
| 1 つまたは複数の bean を削除します（ |
| 完了または破棄された bean をアクティブなステータスで再開します。 |
| リスト/検索/フィルター/ソート/準備完了操作を統合し、GraphQL パススルーを提供します。 |
|
|
| 拡張機能の出力ログを読み取るか、ガイダンスを表示します。 |
beans_query ツールは意図的に広範です。bean のリスト、検索、フィルター、ソート、および Copilot 指示の生成（operation: 'llm_context'）にはこちらを推奨します。
すべてのファイルおよびログ操作はパスを検証し、ワークスペースまたは VS Code のログディレクトリ内に収まるようにします。.beans/ プレフィックスは自動的にパスから削除されます。some-bean.md または .beans/some-bean.md のどちらを渡しても結果は同じです。
beans_update は多くの細かい更新ツールを置き換えます。呼び出し側はこれを使用して、公開ツールの表面を小さく予測可能に保つ必要があります。
beans_archive は、完了/破棄された bean をアーカイブするための CLI パリティを提供します。
beans_update で親 bean を閉じる（status: completed または status: scrapped）と、同じステータスがすべての子孫にカスケードされます。
beans_reopen で親 bean を再開すると、対象のステータスが閉じられた子孫（completed / scrapped）にカスケードされます。
beans_bulk_create および beans_bulk_update はベストエフォートです。各項目を順次処理し、アトミックに失敗するのではなく、項目ごとの成功/エラーエントリを含む配列を返します。
フロントマターの title: 値は書き込み時に自動的に二重引用符で囲まれます。生のタイトルを渡してください。引用符とエスケープは自動処理されます。
beans_bean_file は update_frontmatter をサポートし、アトミックなフロントマターのみの書き込みを行います。サポートされるフィールドには pr と branch が含まれます。
フィルタリングされていないリスト結果は、短いバースト TTL とタイムスタンププローブによるリフレッシュ戦略でキャッシュされます。変更ツール（beans_create、beans_update、beans_delete など）はキャッシュを即座に無効化します。
beans-mcp と Beans CLI のバージョン不一致は警告のみで、ブロックはしない設計です。
ツール入力で beanId が欠落している場合、バリデーションエラーにはヒントが含まれます: 「beanId」のことですか？
リクエスト:
{ "prefix": "project" }レスポンス（structuredContent）:
{ "initialized": true }リクエスト:
{ "beanId": "bean-abc" }リクエスト（複数の bean）:
{ "beanIds": ["bean-abc", "bean-def"] }レスポンス（structuredContent）:
{
"bean": {
"id": "bean-abc",
"title": "Fix login timeout",
"status": "todo",
"type": "bug",
"priority": "critical",
"body": "...markdown...",
"createdAt": "2025-12-01T12:00:00Z",
"updatedAt": "2025-12-02T08:00:00Z"
}
}リクエスト:
{}レスポンス（例）:
{ "archived": true, "archivedCount": 3 }リクエスト:
{
"title": "Add dark mode",
"type": "feature",
"status": "todo",
"priority": "normal",
"body": "Implement theme toggle and styles",
"parent": "epic-123"
}
descriptionはbodyの非推奨エイリアスとして受け入れられます。
レスポンス（structuredContent）:
{
"bean": {
"id": "new-1",
"title": "Add dark mode",
"status": "todo",
"type": "feature"
}
}リクエスト:
{
"parent": "epic-123",
"beans": [
{ "title": "Design mockups", "type": "task" },
{ "title": "Implement API", "type": "task", "priority": "high" },
{ "title": "Write tests", "type": "task", "parent": "epic-456" }
]
}トップレベルの parent は、独自の parent を指定しない bean にデフォルトとして適用されます。ここでは Design mockups と Implement API が epic-123 に割り当てられ、Write tests は epic-456 で上書きされます。
レスポンス（structuredContent）:
{
"requestedCount": 3,
"successCount": 3,
"failedCount": 0,
"results": [
{ "bean": { "id": "task-1", "title": "Design mockups" } },
{ "bean": { "id": "task-2", "title": "Implement API" } },
{ "bean": { "id": "task-3", "title": "Write tests" } }
]
}リクエスト（タスクのバッチを進行中に移動し、親に割り当てる）:
{
"parent": "epic-123",
"beans": [
{ "beanId": "task-1", "status": "in-progress" },
{ "beanId": "task-2", "status": "in-progress" },
{ "beanId": "task-3", "status": "in-progress", "parent": "epic-456" }
]
}レスポンス（structuredContent）:
{
"requestedCount": 3,
"successCount": 3,
"failedCount": 0,
"results": [
{ "beanId": "task-1", "bean": { "id": "task-1", "status": "in-progress" } },
{ "beanId": "task-2", "bean": { "id": "task-2", "status": "in-progress" } },
{ "beanId": "task-3", "bean": { "id": "task-3", "status": "in-progress" } }
]
}両方の一括ツールはベストエフォートです。部分的な失敗はバッチ全体を中断するのではなく、項目ごとに報告されます。
リクエスト（ステータス変更と blocking の追加）:
{
"beanId": "bean-abc",
"status": "in-progress",
"blocking": ["bean-def"],
"ifMatch": "etag-value"
}リクエスト（アトミックな本文変更）:
{
"beanId": "bean-abc",
"bodyReplace": [
{ "old": "- [ ] Task 1", "new": "- [x] Task 1" },
{ "old": "- [ ] Task 2", "new": "- [x] Task 2" }
],
"bodyAppend": "## Summary\n\nAll checklist items completed."
}注:
body（完全置換）は、同じリクエスト内でbodyAppendまたはbodyReplaceと組み合わせることはできません。
レスポンス（structuredContent）:
{
"bean": {
"id": "bean-abc",
"status": "in-progress",
"blockingIds": ["bean-def"]
}
}リクエスト:
{ "beanId": "bean-old", "force": false }レスポンス:
{ "deleted": true, "beanId": "bean-old" }バッチリクエスト:
{ "beanIds": ["bean-old", "bean-older"], "force": false }バッチレスポンス（概要）:
{
"requestedCount": 2,
"deletedCount": 2,
"failedCount": 0,
"results": [
{ "beanId": "bean-old", "deleted": true },
{ "beanId": "bean-older", "deleted": true }
]
}リクエスト:
{
"beanId": "bean-closed",
"requiredCurrentStatus": "completed",
"targetStatus": "todo"
}レスポンス:
{ "bean": { "id": "bean-closed", "status": "todo" } }リクエスト:
{ "beanId": "bean-abc" }レスポンス:
{
"bean": {
"id": "bean-abc",
"status": "todo"
},
"totalTaskCount": 5,
"updatedTaskCount": 3,
"unchangedTaskCount": 2
}リフレッシュ（すべての bean をリスト）:
{ "operation": "refresh" }レスポンス（一部）:
{ "count": 12, "beans": [] }フィルター（ステータス/タイプ/タグ）:
{
"operation": "filter",
"statuses": ["in-progress", "todo"],
"types": ["bug", "feature"],
"tags": ["auth"]
}検索（全文）:
{ "operation": "search", "search": "authentication", "includeClosed": false }ソート（モード: status-priority-type-title、updated、created、id）:
{ "operation": "sort", "mode": "updated" }準備完了（アクション可能な bean のみ）:
{ "operation": "ready" }LLM コンテキスト（Copilot 指示を生成、オプションでワークスペースに書き込み）:
{ "operation": "llm_context", "writeToWorkspaceInstructions": true }レスポンス（structuredContent）:
{
"graphqlSchema": "...",
"generatedInstructions": "...",
"instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}生の GraphQL パススルー（beans query との CLI パリティ）:
{
"operation": "graphql",
"graphql": "{ beans(filter: { type: [\"bug\"] }) { id title status } }"
}変数あり:
{
"operation": "graphql",
"graphql": "query($q: String!) { beans(filter: { search: $q }) { id title } }",
"variables": { "q": "authentication" }
}リクエスト（読み取り）:
{ "operation": "read", "path": "beans-vscode-123--title.md" }レスポンス:
{
"path": "/workspace/.beans/beans-vscode-123--title.md",
"content": "---\n...frontmatter...\n---\n# Title\n"
}リクエスト（アトミックなフロントマター更新）:
{
"operation": "update_frontmatter",
"path": "beans-vscode-123--title.md",
"fields": {
"status": "in-progress",
"pr": "123",
"branch": "feature/cascade-status-and-skills-npm"
}
}レスポンス:
{
"path": "/workspace/.beans/beans-vscode-123--title.md",
"bytes": 256,
"updatedFields": ["status", "pr", "branch"],
"frontmatter": {
"status": "in-progress",
"pr": "123",
"branch": "feature/cascade-status-and-skills-npm"
}
}リクエスト（最後の 200 行を読み取り）:
{ "operation": "read", "lines": 200 }レスポンス:
{
"path": "/workspace/.vscode/logs/beans-output.log",
"content": "...log lines...",
"linesReturned": 200
}npm install beans-mcpimport { createBeansMcpServer, parseCliArgs } from '@selfagency/beans-mcp';
const server = await createBeansMcpServer({
workspaceRoot: '/path/to/workspace',
cliPath: 'beans', // or path to beans CLI
});
// Connect to stdio transport or your own transportBeans MCP サーバーインスタンスを作成して初期化します。
オプション:
workspaceRoot（文字列）: Beans ワークスペースへのパス
cliPath（文字列、オプション）: Beans CLI 実行可能ファイルへのパス（デフォルト: 'beans'）
name（文字列、オプション）: サーバー名（デフォルト: 'beans-mcp-server'）
version（文字列、オプション）: サーバーバージョン
logDir（文字列、オプション）: サーバーログのディレクトリ
backend（BackendInterface、オプション）: カスタムバックエンド実装
戻り値: { server: McpServer; backend: BackendInterface }
サーバーを起動するための CLI 互換エントリポイント。
parseCliArgs(argv: string[]): CLI 引数を解析します
isPathWithinRoot(root: string, target: string): boolean: パスがルート内に含まれているか確認します
sortBeans(beans, mode): 指定されたモードで bean をソートします
GraphQL スキーマ、Zod バリデーションスキーマ、および Beans レコードと操作用の TypeScript 型のエクスポート。
skills-npm、skills.sh）このパッケージには、skills/ 下に組み込みのエージェントスキルが同梱されており、skills.sh によって公開されているより広範なオープンスキルエコシステムに適合する形式でもそのスキルを公開しています。
パッケージ内のスキルパス: skills/beans-mcp/SKILL.md
公開されたスキルアーティファクト: https://beans-mcp.self.agency/.well-known/agent-skills/beans-mcp/SKILL.md
公開されたディスカバリーインデックス: https://beans-mcp.self.agency/.well-known/agent-skills/index.json
以下をスキャンするディスカバリーツールと互換性あり: node_modules/**/skills/*/SKILL.md
つまり、skills-npm のような npm ベースのワークフローで使用できると同時に、skills.sh のようなスキルカタログで使用される公開スキルアーティファクトとディスカバリーインデックスをエコシステムツールが参照することも可能です。
インストールされた npm パッケージのスキルをエージェントワークスペースにシンボリックリンクするには、利用側プロジェクトで skills-npm を使用できます。
MIT
This server cannot be deployed
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Linear project management and issue tracking
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Kaiku is an issue tracker with a wiki, built so that people and AI agents work in the same place. Its hosted MCP server lets an agent search, read, file and update issues, comment and answer questions, read and write wiki pages, and attach files — with the permissions of the person whose token it uses. Create a token in Settings → Connect over MCP and send it as Authorization: Bearer <token> (or in X-Api-Key); the token says which workspace.
