@selfagency/beans-mcp 0.1.0 → 0.1.1

package/.beans.yml

@@ -0,0 +1,6 @@
+beans:
+    path: .beans
+    prefix: beans-mcp-server-
+    id_length: 4
+    default_status: todo
+    default_type: task

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node /Users/daniel/Developer/beans-mcp-server/dist/index.cjs)",
+      "Bash(echo \"Exit: $?\")",
+      "Bash(pnpm run build)",
+      "Bash(node /Users/daniel/Developer/beans-mcp-server/dist/beans-mcp-server.cjs --help)",
+      "Bash(pnpm test)",
+      "Bash(pnpm test src/test/protocol.e2e.test.ts)",
+      "Bash(python3 -c \"import sys,json; p=json.load\\(sys.stdin\\); print\\(p.get\\(''version''\\)\\); print\\(list\\(p.get\\(''exports'',{}\\).keys\\(\\)\\)[:15]\\)\")",
+      "Bash(node -e \"const {z} = require\\(''./node_modules/zod''\\); const s = z.string\\(\\); console.log\\(''v4 internal marker:'', !!s._zod\\); console.log\\(''v3 internal marker:'', !!s._def\\);\")",
+      "Bash(pnpm run type-check)",
+      "Bash(pnpm build)",
+      "Bash(pnpm test --coverage)",
+      "Bash(git add README.md package.json scripts/write-dist-package.js src/cli.ts src/internal/queryHelpers.ts src/server/BeansMcpServer.ts src/server/backend.ts src/test/BeansMcpServer.test.ts src/test/handlers.unit.test.ts src/test/parseCliArgs.test.ts src/test/queryHelpers.test.ts tsup.config.ts src/test/protocol.e2e.test.ts src/test/startBeansMcpServer.test.ts CHANGELOG.md)"
+    ]
+  }
+}

package/.editorconfig

@@ -0,0 +1,13 @@
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+
+[*.cs] 
+indent_size = 4

package/.github/workflows/release.yml

@@ -0,0 +1,235 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 1.2.3)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  detect-tag:
+    name: Detect release tag and readiness
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      actions: read
+
+    outputs:
+      release_tag: ${{ steps.tag.outputs.release_tag }}
+      ready: ${{ steps.tag.outputs.ready }}
+
+    steps:
+      - name: Resolve tag and verify CI readiness
+        id: tag
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            let tagName;
+
+            if (context.eventName === 'workflow_dispatch') {
+              const versionInput = '${{ inputs.version }}'.trim();
+              if (!versionInput) {
+                core.setFailed('version input is required for workflow_dispatch.');
+                return;
+              }
+              tagName = versionInput.startsWith('v') ? versionInput : `v${versionInput}`;
+
+              // Resolve HEAD of main
+              const main = await github.rest.repos.getBranch({ owner, repo, branch: 'main' });
+              const mainSha = main.data.commit.sha;
+
+              // Create the tag via API
+              core.info(`Creating tag ${tagName} at ${mainSha}...`);
+              await github.rest.git.createRef({
+                owner,
+                repo,
+                ref: `refs/tags/${tagName}`,
+                sha: mainSha,
+              });
+              core.info(`Tag ${tagName} created.`);
+            } else {
+              tagName = context.ref.replace('refs/tags/', '');
+            }
+
+            if (!tagName || !tagName.startsWith('v')) {
+              core.info(`Ref '${context.ref}' is not a release tag; skipping.`);
+              core.setOutput('release_tag', '');
+              core.setOutput('ready', 'false');
+              return;
+            }
+
+            const refData = await github.rest.git.getRef({
+              owner,
+              repo,
+              ref: `tags/${tagName}`,
+            });
+
+            const refObj = refData.data.object;
+            const taggedSha =
+              refObj.type === 'tag'
+                ? (await github.rest.git.getTag({ owner, repo, tag_sha: refObj.sha })).data.object.sha
+                : refObj.sha;
+            const main = await github.rest.repos.getBranch({ owner, repo, branch: 'main' });
+            const mainSha = main.data.commit.sha;
+
+            if (taggedSha !== mainSha) {
+              core.setFailed(
+                `Release blocked: tag ${tagName} points to ${taggedSha}, but latest main is ${mainSha}.`
+              );
+              return;
+            }
+
+            // Verify the full test suite passed on this commit.
+            const requiredWorkflows = ['Test & Build'];
+
+            for (const workflowName of requiredWorkflows) {
+              const workflowsResp = await github.rest.actions.listRepoWorkflows({
+                owner,
+                repo,
+                per_page: 100,
+              });
+
+              const workflow = workflowsResp.data.workflows.find(w => w.name === workflowName);
+              if (!workflow) {
+                core.setFailed(`Release blocked: required workflow '${workflowName}' not found in repository.`);
+                return;
+              }
+
+              const runsResp = await github.rest.actions.listWorkflowRuns({
+                owner,
+                repo,
+                workflow_id: workflow.id,
+                branch: 'main',
+                head_sha: mainSha,
+                status: 'completed',
+                per_page: 10,
+              });
+
+              const run = runsResp.data.workflow_runs[0];
+              if (!run) {
+                core.setFailed(
+                  `Release blocked: required workflow '${workflowName}' has no completed run for ${mainSha}.`
+                );
+                return;
+              }
+              if (run.conclusion !== 'success') {
+                core.setFailed(
+                  `Release blocked: workflow '${workflowName}' concluded with '${run.conclusion}' on ${mainSha}.`
+                );
+                return;
+              }
+            }
+
+            core.info(`Release tag detected: ${tagName} on latest main commit ${mainSha}; all checks passed.`);
+            core.setOutput('release_tag', tagName);
+            core.setOutput('ready', 'true');
+
+  release:
+    name: Build and Release
+    needs: detect-tag
+    if: needs.detect-tag.outputs.release_tag != '' && needs.detect-tag.outputs.ready == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.detect-tag.outputs.release_tag }}
+          fetch-depth: 0
+
+      - name: Generate release notes
+        id: changelog_notes
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const currentTag = '${{ needs.detect-tag.outputs.release_tag }}';
+
+            const tagsResp = await github.rest.repos.listTags({
+              owner,
+              repo,
+              per_page: 100,
+            });
+            const tags = tagsResp.data;
+
+            const index = tags.findIndex(tag => tag.name === currentTag);
+            const previousTag =
+              index >= 0
+                ? (tags.slice(index + 1).find(tag => tag.name.startsWith('v'))?.name ?? '')
+                : '';
+
+            const notesResponse = await github.rest.repos.generateReleaseNotes({
+              owner,
+              repo,
+              tag_name: currentTag,
+              ...(previousTag ? { previous_tag_name: previousTag } : {}),
+              target_commitish: 'main',
+            });
+
+            core.info(
+              previousTag
+                ? `Generated changelog notes from ${previousTag} to ${currentTag}.`
+                : `Generated changelog notes for ${currentTag} (no previous tag found).`
+            );
+
+            core.setOutput('previous_tag', previousTag);
+            core.setOutput('notes', notesResponse.data.body ?? '');
+
+      - name: Write release notes to file
+        run: printf '%s' "$RELEASE_NOTES" > release-notes.md
+        env:
+          RELEASE_NOTES: ${{ steps.changelog_notes.outputs.notes }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Pack npm tarball
+        run: npm pack ./dist --pack-destination .
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.detect-tag.outputs.release_tag }}
+          body_path: release-notes.md
+          files: "*.tgz"
+          draft: false
+          prerelease: ${{ contains(needs.detect-tag.outputs.release_tag, '-') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

package/.github/workflows/test.yml

@@ -0,0 +1,80 @@
+name: Test & Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Get pnpm store directory
+        id: pnpm-store
+        shell: bash
+        run: |
+          # pnpm may return a non-zero code in some environments; fall back to a sane default
+          STORE_PATH="$(pnpm store path 2>/dev/null || echo "${HOME}/.pnpm-store")"
+          echo "store-path=$STORE_PATH" >> $GITHUB_OUTPUT
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.store-path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: pnpm type-check
+
+      - name: Lint
+        run: pnpm lint
+        continue-on-error: true
+
+      - name: Build
+        run: pnpm build
+
+      - name: Verify build outputs
+        run: |
+          test -f dist/index.js || exit 1
+          test -f dist/index.cjs || exit 1
+          test -f dist/beans-mcp-server.cjs || exit 1
+          test -f dist/index.d.ts || exit 1
+          echo "✓ All build outputs verified"
+
+      - name: Test
+        run: pnpm test:coverage --reporter=junit --outputFile=test-report.junit.xml
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.nvmrc

@@ -0,0 +1 @@
+20

package/.oxfmtrc.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "ignorePatterns": ["node_modules", "dist"],
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "printWidth": 120,
+  "proseWrap": "preserve",
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2
+}

package/.oxlintrc.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": [
+    "unicorn",
+    "typescript",
+    "oxc",
+    "import",
+    "promise",
+    "node",
+    "vitest"
+  ],
+  "categories": {},
+  "rules": {},
+  "settings": {
+    "jsdoc": {
+      "ignorePrivate": false,
+      "ignoreInternal": false,
+      "ignoreReplacesDocs": true,
+      "overrideReplacesDocs": true,
+      "augmentsExtendsReplacesDocs": false,
+      "implementsReplacesDocs": false,
+      "exemptDestructuredRootsFromChecks": false,
+      "tagNamePreference": {}
+    },
+    "vitest": {
+      "typecheck": false
+    }
+  },
+  "env": {
+    "builtin": true
+  },
+  "globals": {},
+  "ignorePatterns": [
+    "node_modules",
+    "dist"
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.defaultFormatter": "oxc.oxc-vscode"
+}

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# 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

@@ -0,0 +1,139 @@
+# 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.