MCP (Model Context Protocol) 서버 for Beans 이슈 트래커. AI 기반 상호작용을 위한 프로그래밍 방식 및 CLI 인터페이스를 제공합니다.
🤖 VS Code에서 GitHub Copilot과 완전히 통합된 Beans를 사용해보세요! 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 생성 (제목/유형 + 선택적 본문/부모). |
| 한 번의 호출로 여러 bean 생성, 선택적으로 공유 부모 아래에 생성. |
| 통합 메타데이터 + 본문 업데이트 (상태/유형/우선순위/부모/clearParent/blocking/blockedBy/본문/bodyAppend/bodyReplace) 및 선택적 낙관적 동시성 힌트 ( |
| 한 번의 호출로 여러 bean 업데이트, 선택적으로 공유 부모로 재할당. |
| bean 내 모든 마크다운 체크리스트 작업을 완료로 표시. |
| 하나 또는 여러 bean 삭제 ( |
| 완료 또는 폐기된 bean을 활성 상태로 다시 열기. |
| 통합 목록/검색/필터/정렬/준비 작업, GraphQL 패스스루 포함. |
|
|
| 확장 출력 로그 읽기 또는 안내 표시. |
beans_query 도구는 의도적으로 광범위합니다: beans 목록, 검색, 필터링 또는 정렬, 그리고 Copilot 명령 생성(operation: 'llm_context')에 사용하세요.
모든 파일 및 로그 작업은 경로를 검증하여 작업 공간 또는 VS Code 로그 디렉터리 내에 유지합니다. .beans/ 접두사는 경로에서 자동으로 제거됩니다 — some-bean.md 또는 .beans/some-bean.md를 전달해도 결과는 동일합니다.
beans_update는 여러 세분화된 업데이트 도구를 대체합니다. 호출자는 이를 사용하여 공개 도구 표면을 작고 예측 가능하게 유지해야 합니다.
beans_archive는 완료/폐기된 beans 보관 처리를 위한 CLI 패리티를 제공합니다.
beans_update를 통해 부모 bean을 닫으면(status: completed 또는 status: scrapped) 동일한 상태가 모든 하위 항목에 계단식으로 적용됩니다.
beans_reopen을 통해 부모 bean을 다시 열면 대상 상태가 닫힌 하위 항목(completed / scrapped)에 계단식으로 적용됩니다.
beans_bulk_create 및 beans_bulk_update는 최선 방식입니다: 각 항목을 순차적으로 처리하고 원자적으로 실패하지 않고 항목별 결과 배열(성공/오류 항목)을 반환합니다.
Frontmatter title: 값은 쓰기 시 자동으로 큰따옴표로 묶입니다. 원시 제목을 전달하세요 — 인용 및 이스케이프는 자동으로 처리됩니다.
beans_bean_file은 원자적 frontmatter 전용 쓰기를 위한 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"
}요청 (원자적 frontmatter 업데이트):
{
"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): 지정된 모드로 beans 정렬
Beans 레코드 및 작업에 대한 GraphQL 스키마, Zod 유효성 검사 스키마 및 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.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
