@selfagency/beans-mcp 0.1.3 → 0.4.2

package/.github/workflows/release.yml

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

@@ -1,84 +0,0 @@
-name: Test & Build
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-permissions:
-  contents: read
-  pull-requests: write
-
-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

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

package/.nvmrc

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

package/.oxfmtrc.json

@@ -1,11 +0,0 @@
-{
-  "$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

@@ -1,37 +0,0 @@
-{
-  "$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

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

package/CHANGELOG.md

@@ -1,160 +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.3] - 2026-02-27
-
-**Full Changelog**: https://github.com/selfagency/beans-mcp/compare/v0.1.2...v0.1.3
-
-_Source: changes from v0.1.2 to v0.1.3._
-
-
-## [0.1.2] - 2026-02-27
-
-## What's Changed
-* feat: support body updates and de-duplicate MCP results by @selfagency in https://github.com/selfagency/beans-mcp/pull/1
-
-## New Contributors
-* @selfagency made their first contribution in https://github.com/selfagency/beans-mcp/pull/1
-
-**Full Changelog**: https://github.com/selfagency/beans-mcp/compare/v0.1.1...v0.1.2
-
-_Source: changes from v0.1.1 to v0.1.2._
-
-
-## [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/LICENSE.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 The Self Agency, LLC
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.