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.
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.
