@selfagency/beans-mcp 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,140 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.1.1] - 2026-02-25
-
-**Full Changelog**: https://github.com/selfagency/beans-mcp/compare/v0.1.0...v0.1.1
-
-_Source: changes from v0.1.0 to v0.1.1._
-
-
-## [0.1.0] - 2026-02-25
-
-**Full Changelog**: https://github.com/selfagency/beans-mcp/commits/v0.1.0
-
-
-Initial public release. Extracted and substantially reworked from the
-[selfagency.beans-vscode](https://marketplace.visualstudio.com/items?itemName=selfagency.beans-vscode)
-VS Code extension's embedded MCP server into a standalone, independently
-installable package.
-
-### Added
-
-#### MCP Tools
-
-All 14 Beans MCP tools are implemented and registered:
-
-- `beans_init` — Initialize the workspace (optional prefix).
-- `beans_list` — List beans with filtering by status, type, tags, and search.
-- `beans_view` — View a single bean by ID.
-- `beans_create` — Create a new bean.
-- `beans_update` / `beans_edit` — Update an existing bean (aliases).
-- `beans_reopen` — Reopen a completed or scrapped bean.
-- `beans_delete` — Delete a draft or scrapped bean.
-- `beans_set_status` — Set a bean's status directly.
-- `beans_query` — Run llm_context, refresh, and workspace-instructions operations.
-- `beans_bean_file` — Read, edit, create, or delete raw bean markdown files.
-- `beans_output` — Read the Beans CLI output log.
-- `beans_open_config` — Return the workspace config file path and content.
-- `beans_graphql_schema` — Return the Beans GraphQL schema.
-
-#### Public API
-
-- `createBeansMcpServer(opts)` — Programmatic factory for embedding a Beans
-  MCP server in other applications; accepts an optional `backend` parameter
-  for dependency injection.
-- `startBeansMcpServer(argv)` — CLI entrypoint; launches the server with a
-  `StdioServerTransport`.
-- `parseCliArgs(argv)` — Parse and validate CLI arguments; returns a
-  `workspaceExplicit` flag so callers can distinguish user-supplied roots from
-  the cwd default.
-- `BeansCliBackend` — Concrete backend that shells out to the `beans` CLI.
-- `BackendInterface` — Interface for custom backend implementations.
-- `MutableBackend` — Thin delegation wrapper whose inner backend can be
-  hot-swapped after MCP roots discovery without re-registering tools.
-- `resolveWorkspaceFromRoots(server)` — Queries the connected client's
-  declared MCP roots and returns the first `file://` path as a local workspace
-  path, or `null` if none are declared.
-- `sortBeans`, `isPathWithinRoot`, `makeTextAndStructured` — Utility helpers.
-
-#### Workspace Resolution
-
-The server resolves its workspace in priority order:
-
-1. `--workspace-root` / positional CLI argument (explicit)
-2. MCP roots declared by the connected client (`roots/list`)
-3. `process.cwd()` (fallback)
-
-This enables using the server without CLI arguments: AI clients that declare
-MCP roots (e.g. Cursor, Claude Desktop) automatically provide the workspace
-path after connecting.
-
-#### CLI
-
-- `beans-mcp` binary accepts:
-  - Positional or `--workspace-root` for the workspace path.
-  - `--cli-path` — path to the `beans` executable (default: `beans`).
-  - `--port` — MCP server port (default: 39173).
-  - `--log-dir` — log directory (defaults to workspace root).
-  - `-h` / `--help` — print usage and exit.
-
-#### Build
-
-- Multi-config `tsup.config.ts` produces three outputs:
-  - ESM library (`dist/index.js` + `dist/index.d.ts`)
-  - CJS library (`dist/index.cjs`)
-  - CJS CLI binary (`dist/beans-mcp-server.cjs`) with `#!/usr/bin/env node` shebang
-- All CJS configs use `target: 'node18'`, `splitting: false`, `cjsInterop: true`.
-- `postbuild` script writes a trimmed `dist/package.json` with correct `bin`,
-  `exports`, `main`, `module`, and `types` fields.
-
-#### Tests
-
-- **Protocol E2E tests** (`src/test/protocol.e2e.test.ts`) — 52 tests using
-  `InMemoryTransport` + MCP `Client` to exercise the full JSON-RPC wire format,
-  Zod input validation, backend error surfacing as `{ isError: true }` tool
-  results, and the MCP roots protocol.
-- **`startBeansMcpServer` integration tests** (`src/test/startBeansMcpServer.test.ts`)
-  — mocked dynamic imports for `BeansCliBackend` and `StdioServerTransport`.
-- Handler unit tests — exported handler factories tested in isolation.
-- `MutableBackend` unit tests — delegation and `setInner` swap behaviour.
-- `resolveWorkspaceFromRoots` unit tests — all branches (found, skipped,
-  empty list, throws).
-- `parseCliArgs` tests — `workspaceExplicit` flag, `--help`/`-h` output and
-  exit code.
-- Statement and function coverage: **100%** for `BeansMcpServer.ts`.
-
-#### CI
-
-- GitHub Actions workflow runs lint, type-check, build, and test on Node 18
-  and 22 across Ubuntu and macOS.
-- pnpm store cache keyed on lockfile hash with `~/.pnpm-store` fallback.
-
-### Changed
-
-- Tool IDs renamed to remove the `_vscode` suffix carried over from the
-  extension (e.g. `beans_init_vscode` → `beans_init`).
-- `--log-dir` now defaults to the workspace root when omitted.
-- `cli.ts` simplified: removed the `isMainModule` guard; always invokes
-  `startBeansMcpServer`.
-- Bin command renamed from `beans-mcp-server` to `beans-mcp`.
-
-### Fixed
-
-- Build script was overriding `tsup.config.ts` with inline CLI flags, causing
-  the CLI binary to never be produced. Fixed by setting `"build": "tsup"`.
-- `package.json` exports paths corrected to include the `dist/` prefix.
-- Eliminated all `any` types: `queryHandler` opts, `backend.ts` filter
-  parameter, and `queryHelpers.ts` return type narrowed to
-  `Record<string, unknown>`.
-- README: corrected package import name (`@selfagency/beans-mcp`), server
-  default name (`beans-mcp-server`), removed the non-existent `allowedRoots`
-  option from the `createBeansMcpServer` docs.
-
-[Unreleased]: https://github.com/selfagency/beans-mcp/compare/v0.1.0...HEAD

package/CONTRIBUTING.md

@@ -1,139 +0,0 @@
-# Contributing to beans-mcp-server
-
-Thank you for your interest in contributing to the Beans MCP server! This document provides guidelines and instructions for contributing.
-
-## Development Setup
-
-### Prerequisites
-
-- Node.js 18+
-- pnpm 9+
-- Beans CLI installed and in PATH (or specify via `--cli-path`)
-
-### Getting Started
-
-1. Clone the repository
-2. Install dependencies:
-
-   ```bash
-   pnpm install
-   ```
-
-3. Build the project:
-
-   ```bash
-   pnpm build
-   ```
-
-4. Run tests:
-
-   ```bash
-   pnpm test
-   ```
-
-## Development Workflow
-
-### Running Tests
-
-```bash
-# Run all tests
-pnpm test
-
-# Run specific test file
-pnpm test src/test/utils.test.ts
-
-# Run with coverage
-pnpm test --coverage
-```
-
-### Building
-
-The project uses `tsup` for bundling:
-
-```bash
-# Build all formats (ESM, CJS, CLI)
-pnpm build
-
-# Watch mode (development)
-pnpm build --watch
-```
-
-Build outputs:
-
-- `dist/index.js` - ESM entry point
-- `dist/index.cjs` - CommonJS entry point
-- `dist/beans-mcp-server.cjs` - CLI executable (with shebang)
-- `dist/index.d.ts` - TypeScript type definitions
-
-### Code Style
-
-- Use TypeScript for all source code
-- Format with Prettier (configured in project)
-- Lint with ESLint
-- Follow existing patterns in the codebase
-
-### Testing Requirements
-
-- All changes should include tests
-- Use Vitest for unit tests
-- Tests should use Arrange-Act-Assert pattern
-- Aim for high test coverage
-
-## Architecture
-
-### Project Structure
-
-```text
-src/
-├── index.ts              # Public API exports
-├── cli.ts                # CLI entry point
-├── types.ts              # TypeScript types and constants
-├── utils.ts              # Utility functions
-├── server/
-│   ├── BeansMcpServer.ts # Main MCP server implementation
-│   └── backend.ts        # Backend interface and Beans CLI backend
-├── internal/
-│   ├── graphql.ts        # GraphQL queries/mutations
-│   └── queryHelpers.ts   # Query and sorting utilities
-└── test/
-    ├── utils.test.ts
-    └── parseCliArgs.test.ts
-```
-
-### Key Modules
-
-- **BeansMcpServer.ts**: Main server class that manages MCP tools and backend interaction
-- **backend.ts**: Interface for backend implementations; includes BeansCliBackend that wraps Beans CLI
-- **graphql.ts**: GraphQL queries and mutations for bean operations
-- **queryHelpers.ts**: Sorting, filtering, and query handling utilities
-
-## Submitting Changes
-
-1. Create a feature branch from `main`
-2. Make your changes with clear, atomic commits
-3. Add or update tests as needed
-4. Run `pnpm test` to ensure all tests pass
-5. Run `pnpm build` to verify the build succeeds
-6. Submit a pull request with a clear description
-
-## Pull Request Guidelines
-
-- Include a clear description of what changed and why
-- Reference any related issues
-- Ensure all tests pass
-- Update documentation if needed
-- Keep commits focused and atomic
-
-## Reporting Issues
-
-When reporting bugs, please include:
-
-- Steps to reproduce
-- Expected behavior
-- Actual behavior
-- Node.js and pnpm versions
-- Relevant error messages or logs
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the MIT License.

package/dist/README.md

@@ -1,307 +0,0 @@
-# @selfagency/beans-mcp 🫘
-
-[![Test & Build](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/selfagency/beans-mcp/graph/badge.svg?token=udeAJyu8Nu)](https://codecov.io/gh/selfagency/beans-mcp)
-
-MCP (Model Context Protocol) server for [Beans](https://github.com/hmans/beans) issue tracker. Provides programmatic and CLI interfaces for AI-powered interactions with Beans workspaces.
-
-> 🤖 **Try Beans fully-integrated with GitHub Copilot in VS Code! Install the <a href="https://marketplace.visualstudio.com/items?itemName=selfagency.beans-vscode">selfagency.beans-vscode</a> extension.**
-
-## Usage
-
-```bash
-npx @selfagency/beans-mcp /path/to/workspace
-```
-
-### Parameters
-
-- `--workspace-root` or positional arg: Workspace root path
-- `--cli-path`: Path to Beans CLI
-- `--port`: MCP server port (default: 39173)
-- `--log-dir`: Log directory
-- `-h`, `--help`: Print usage and exit
-
-## Summary of public MCP tools
-
-- `beans_init` — Initialize the workspace (optional `prefix`).
-- `beans_view` — Fetch full bean details by `beanId`.
-- `beans_create` — Create a new bean (title/type + optional fields).
-- `beans_update` — Consolidated metadata updates (status/type/priority/parent/clearParent/blocking/blockedBy).
-- `beans_delete` — Delete a bean (`beanId`, optional `force`).
-- `beans_reopen` — Reopen a completed or scrapped bean to an active status.
-- `beans_query` — Unified list/search/filter/sort/llm_context/open_config operations.
-- `beans_bean_file` — Read/edit/create/delete files under `.beans`.
-- `beans_output` — Read extension output logs or show guidance.
-
-### Notes
-
-- The `beans_query` tool is intentionally broad: prefer it for listing, searching, filtering or sorting beans, and for generating Copilot instructions (`operation: 'llm_context'`).
-- All file and log operations validate paths to keep them within the workspace or the VS Code log directory.
-- `beans_update` replaces many fine-grained update tools; callers should use it to keep the public tool surface small and predictable.
-
-## Examples
-
-### beans_init
-
-Request:
-
-```json
-{ "prefix": "project" }
-```
-
-Response (structuredContent):
-
-```json
-{ "initialized": true }
-```
-
-### beans_view
-
-Request:
-
-```json
-{ "beanId": "bean-abc" }
-```
-
-Response (structuredContent):
-
-```json
-{
-  "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"
-  }
-}
-```
-
-### beans_create
-
-Request:
-
-```json
-{
-  "title": "Add dark mode",
-  "type": "feature",
-  "status": "todo",
-  "priority": "normal",
-  "description": "Implement theme toggle and styles"
-}
-```
-
-Response (structuredContent):
-
-```json
-{
-  "bean": {
-    "id": "new-1",
-    "title": "Add dark mode",
-    "status": "todo",
-    "type": "feature"
-  }
-}
-```
-
-### beans_update
-
-Request (change status and add blocking):
-
-```json
-{
-  "beanId": "bean-abc",
-  "status": "in-progress",
-  "blocking": ["bean-def"]
-}
-```
-
-Response (structuredContent):
-
-```json
-{
-  "bean": {
-    "id": "bean-abc",
-    "status": "in-progress",
-    "blockingIds": ["bean-def"]
-  }
-}
-```
-
-### beans_delete
-
-Request:
-
-```json
-{ "beanId": "bean-old", "force": false }
-```
-
-Response:
-
-```json
-{ "deleted": true, "beanId": "bean-old" }
-```
-
-### beans_reopen
-
-Request:
-
-```json
-{
-  "beanId": "bean-closed",
-  "requiredCurrentStatus": "completed",
-  "targetStatus": "todo"
-}
-```
-
-Response:
-
-```json
-{ "bean": { "id": "bean-closed", "status": "todo" } }
-```
-
-### beans_query — examples
-
-Refresh (list all beans):
-
-```json
-{ "operation": "refresh" }
-```
-
-Response (partial):
-
-```json
-{ "count": 12, "beans": [] }
-```
-
-Filter (statuses/types/tags):
-
-```json
-{
-  "operation": "filter",
-  "statuses": ["in-progress", "todo"],
-  "types": ["bug", "feature"],
-  "tags": ["auth"]
-}
-```
-
-Search (full-text):
-
-```json
-{ "operation": "search", "search": "authentication", "includeClosed": false }
-```
-
-Sort (modes: `status-priority-type-title`, `updated`, `created`, `id`):
-
-```json
-{ "operation": "sort", "mode": "updated" }
-```
-
-LLM context (generate Copilot instructions; optional write-to-workspace):
-
-```json
-{ "operation": "llm_context", "writeToWorkspaceInstructions": true }
-```
-
-Response (structuredContent):
-
-```json
-{
-  "graphqlSchema": "...",
-  "generatedInstructions": "...",
-  "instructionsPath": "/workspace/.github/instructions/tasks.instructions.md"
-}
-```
-
-### beans_bean_file
-
-Request (read):
-
-```json
-{ "operation": "read", "path": "beans-vscode-123--title.md" }
-```
-
-Response:
-
-```json
-{
-  "path": "/workspace/.beans/beans-vscode-123--title.md",
-  "content": "---\n...frontmatter...\n---\n# Title\n"
-}
-```
-
-### beans_output
-
-Request (read last 200 lines):
-
-```json
-{ "operation": "read", "lines": 200 }
-```
-
-Response:
-
-```json
-{
-  "path": "/workspace/.vscode/logs/beans-output.log",
-  "content": "...log lines...",
-  "linesReturned": 200
-}
-```
-
-## Programmatic usage
-
-### Installation
-
-```bash
-npm install beans-mcp
-```
-
-### Example
-
-```typescript
-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)
-
-Creates and initializes a Beans MCP server instance.
-
-**Options:**
-
-- `workspaceRoot` (string): Path to the Beans workspace
-- `cliPath` (string, optional): Path to Beans CLI executable (default: 'beans')
-- `name` (string, optional): Server name (default: 'beans-mcp-server')
-- `version` (string, optional): Server version
-- `logDir` (string, optional): Directory for server logs
-- `backend` (BackendInterface, optional): Custom backend implementation
-
-**Returns:** `{ server: McpServer; backend: BackendInterface }`
-
-#### startBeansMcpServer(argv)
-
-CLI-compatible entrypoint for launching the server.
-
-### Utility Functions
-
-- `parseCliArgs(argv: string[])`: Parse CLI arguments
-- `isPathWithinRoot(root: string, target: string): boolean`: Check if path is contained within root
-- `sortBeans(beans, mode)`: Sort beans by specified mode
-
-### Types & Schemas
-
-Export of GraphQL schema, Zod validation schemas, and TypeScript types for Beans records and operations.
-
-## License
-
-MIT