Skip to main content
Glama
deenesjakoruzh
voxslopuli

@selfagency/beans-mcp

Official
by voxslopuli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@selfagency/beans-mcp 🫘

Test & Build codecov NPM Version

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

公開 MCP ツールの概要

ツール

説明

beans_init

ワークスペースを初期化します（オプションの prefix）。

beans_archive

完了または破棄された beans をアーカイブします。

beans_view

beanId または beanIds で bean の詳細を取得します。

beans_create

新しい bean を作成します（タイトル/タイプ + オプションの body/parent）。

beans_bulk_create

1 回の呼び出しで複数の bean を作成し、オプションで共通の親の下に配置します。

beans_update

メタデータと本文の更新を統合（status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace）し、オプションの楽観的同時実行ヒント（ifMatch）を追加。

beans_bulk_update

1 回の呼び出しで複数の bean を更新し、オプションでそれらを共通の親に再割り当てします。

beans_complete_tasks

bean 内のすべての Markdown チェックリストタスクを完了としてマークします。

beans_delete

1 つまたは複数の bean を削除します（beanId または beanIds、オプションの force）。

beans_reopen

完了または破棄された bean をアクティブなステータスで再開します。

beans_query

リスト/検索/フィルター/ソート/準備完了操作を統合し、GraphQL パススルーを提供します。

beans_bean_file

.beans 下のファイルを読み取り/編集/作成/削除します。

beans_output

拡張機能の出力ログを読み取るか、ガイダンスを表示します。

  • 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-mcp

例

import { 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 transport

API

createBeansMcpServer(opts)

Beans MCP サーバーインスタンスを作成して初期化します。

オプション:

  • workspaceRoot（文字列）: Beans ワークスペースへのパス

  • cliPath（文字列、オプション）: Beans CLI 実行可能ファイルへのパス（デフォルト: 'beans'）

  • name（文字列、オプション）: サーバー名（デフォルト: 'beans-mcp-server'）

  • version（文字列、オプション）: サーバーバージョン

  • logDir（文字列、オプション）: サーバーログのディレクトリ

  • backend（BackendInterface、オプション）: カスタムバックエンド実装

戻り値: { server: McpServer; backend: BackendInterface }

startBeansMcpServer(argv)

サーバーを起動するための 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

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • FogBugz

    todevelopers
    A
    license
    A
    quality
    C
    maintenance
    A MCP server for interacting with FogBugz issue tracker through LLMs such as Claude. Supports both the XML API (/api.asp) and the JSON API (/f/api/0/jsonapi) with automatic version detection at startup. Works with on-premise and on-demand FogBugz installations.
    19
    25 npm
    2
    MIT

  • linear-mcp-server

    dshurick
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for integrating Linear with Claude Code and other MCP clients. Enables issue management, project planning, and status tracking through a set of tools.
    -

  • project-context

    sandovalrr
    A
    license
    Not graded
    quality
    F
    maintenance
    A local, provider-neutral MCP server for repository-scoped issue handling. It provides a guarded interface to Linear, GitHub Issues, GitHub Projects v2, and Jira Cloud, with preview/apply safety and host-local configuration.
    67 npm
    1
    MIT