@selfagency/beans-mcp 🫘

Сервер MCP (Model Context Protocol) для трекера задач Beans. Предоставляет программный и CLI-интерфейсы для AI-взаимодействий с рабочими пространствами Beans.

Документация: beans-mcp.self.agency

🤖 Попробуйте Beans в полной интеграции с GitHub Copilot в VS Code! Установите расширение selfagency.beans-vscode.

Использование

npx @selfagency/beans-mcp /path/to/workspace

Версионирование

@selfagency/beans-mcp имеет собственное версионирование пакета. Совместимость с CLI Beans отслеживается отдельно.

При запуске сервер сравнивает установленную версию CLI beans с жёстко заданной поддерживаемой версией Beans: 0.4.2. Если они различаются, выводится предупреждение в stderr, и запуск продолжается.

Параметры

• --workspace-root или позиционный аргумент: путь к корню рабочего пространства

• --cli-path: путь к CLI Beans

• --port: порт сервера MCP (по умолчанию: 39173)

• --log-dir: каталог для логов

• -h, --help: вывод справки и выход

Related MCP server: jira-cli-mcp

Сводка публичных инструментов MCP

• Инструмент beans_query намеренно широк: предпочитайте его для списка, поиска, фильтрации или сортировки beans, а также для генерации инструкций Copilot (operation: 'llm_context').

• Все операции с файлами и логами проверяют пути, чтобы они оставались в пределах рабочего пространства или каталога логов VS Code. Префикс .beans/ автоматически удаляется из путей — вы можете передать как some-bean.md, так и .beans/some-bean.md, результат будет одинаковым.

• beans_update заменяет множество узкоспециализированных инструментов обновления; вызывающие стороны должны использовать его, чтобы сохранить поверхность публичных инструментов небольшой и предсказуемой.

• beans_archive обеспечивает паритет с CLI для архивирования завершённых/отменённых beans.

• Закрытие родительского bean через beans_update (status: completed или status: scrapped) каскадно применяет тот же статус ко всем потомкам.

• Переоткрытие родительского bean через beans_reopen каскадно применяет целевой статус к закрытым потомкам (completed / scrapped).

• beans_bulk_create и beans_bulk_update работают по принципу «максимальных усилий»: они обрабатывают каждый элемент последовательно и возвращают массив результатов для каждого элемента с записями об успехе/ошибке, а не атомарно.

• Значения title: в frontmatter автоматически заключаются в двойные кавычки при записи. Передавайте сырые заголовки — кавычки и экранирование обрабатываются за вас.

• beans_bean_file поддерживает update_frontmatter для атомарной записи только frontmatter; поддерживаемые поля включают pr и branch.

• Результаты нефильтрованных списков кэшируются с коротким TTL и стратегией обновления по временной метке. Инструменты мутации (beans_create, beans_update, beans_delete и т.д.) немедленно инвалидируют кэш.

• Несоответствия версий между beans-mcp и CLI Beans являются только предупреждениями и не блокируют работу.

• Когда beanId отсутствует во входных данных инструмента, ошибки валидации включают подсказку: Возможно, вы имели в виду \beanId`?`.

Примеры

Запрос:

{ "prefix": "project" }

Ответ (structuredContent):

{ "initialized": true }

Запрос:

{ "beanId": "bean-abc" }

Запрос (несколько beans):

{ "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 применяется как значение по умолчанию для любого bean, который не указывает собственного parent. Здесь 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" } }
  ]
}

Оба массовых инструмента работают по принципу «максимальных усилий»: частичные сбои сообщаются для каждого элемента, а не прерывают всю операцию.

Запрос (изменить статус и добавить блокировку):

{
  "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
}

Обновление (список всех beans):

{ "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" }

Готовность (только активные beans):

{ "operation": "ready" }

Контекст LLM (генерация инструкций Copilot; опциональная запись в рабочее пространство):

{ "operation": "llm_context", "writeToWorkspaceInstructions": true }

Ответ (structuredContent):

{
  "graphqlSchema": "...",
  "generatedInstructions": "...",
  "instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}

Прямая передача GraphQL (паритет с CLI beans query):

{
  "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-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 (string): путь к рабочему пространству Beans

• cliPath (string, опционально): путь к исполняемому файлу CLI Beans (по умолчанию: 'beans')

• name (string, опционально): имя сервера (по умолчанию: 'beans-mcp-server')

• version (string, опционально): версия сервера

• logDir (string, опционально): каталог для логов сервера

• backend (BackendInterface, опционально): пользовательская реализация бэкенда

Возвращает: { server: McpServer; backend: BackendInterface }

startBeansMcpServer(argv)

Точка входа, совместимая с CLI, для запуска сервера.

Вспомогательные функции

• parseCliArgs(argv: string[]): разбор аргументов CLI

• isPathWithinRoot(root: string, target: string): boolean: проверка, находится ли путь внутри корня

• sortBeans(beans, mode): сортировка beans по указанному режиму

Типы и схемы

Экспорт схемы GraphQL, схем валидации Zod и TypeScript-типов для записей и операций Beans.

Навыки агента (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

Это означает, что вы можете использовать его с npm-ориентированными рабочими процессами, такими как skills-npm, а также указывать инструментам экосистемы на опубликованный артефакт навыка и индекс обнаружения, используемые каталогами навыков, такими как skills.sh.

Чтобы создать символическую ссылку на установленные npm-пакеты навыков в вашем рабочем пространстве агента, вы можете использовать skills-npm в вашем потребляющем проекте.

Лицензия

MIT