@selfagency/beans-mcp 0.1.3 → 0.1.4

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.

package/codeql/codeql-custom-queries-actions/README.md

@@ -1,14 +0,0 @@
-# Custom CodeQL Queries (GitHub Actions)
-
-This pack adds repository-specific hardening checks for workflow security.
-
-## Queries
-
-- `queries/strict-external-action-pinning.ql`
-  - Flags external `uses:` steps that are not pinned to a full 40-character commit SHA.
-- `queries/github-script-without-tojson.ql`
-  - Flags `actions/github-script` steps whose `script` argument does not appear to use `toJson(...)`.
-
-## Why these checks
-
-These checks focus on practical workflow hardening against supply-chain and interpolation risks while keeping alerts actionable.

package/codeql/codeql-custom-queries-actions/codeql-pack.lock.yml

@@ -1,32 +0,0 @@
----
-lockVersion: 1.0.0
-dependencies:
-  codeql/actions-all:
-    version: 0.4.27
-  codeql/concepts:
-    version: 0.0.15
-  codeql/controlflow:
-    version: 2.0.25
-  codeql/dataflow:
-    version: 2.0.25
-  codeql/javascript-all:
-    version: 2.6.21
-  codeql/mad:
-    version: 1.0.41
-  codeql/regex:
-    version: 1.0.41
-  codeql/ssa:
-    version: 2.0.17
-  codeql/threat-models:
-    version: 1.0.41
-  codeql/tutorial:
-    version: 1.0.41
-  codeql/typetracking:
-    version: 2.0.25
-  codeql/util:
-    version: 2.0.28
-  codeql/xml:
-    version: 1.0.41
-  codeql/yaml:
-    version: 1.0.41
-compiled: false

package/codeql/codeql-custom-queries-actions/codeql-pack.yml

@@ -1,7 +0,0 @@
----
-library: false
-warnOnImplicitThis: false
-name: getting-started/codeql-extra-queries-actions
-version: 1.0.0
-dependencies:
-  codeql/actions-all: ^0.4.27

package/codeql/codeql-custom-queries-actions/qlpack.yml

@@ -1,6 +0,0 @@
-library: false
-warnOnImplicitThis: false
-name: selfagency/beans-vscode-codeql-extra-queries-actions
-version: 1.0.0
-dependencies:
-  codeql/actions-all: ^0.4.27

package/codeql/codeql-custom-queries-actions/queries/github-script-without-tojson.ql

@@ -1,18 +0,0 @@
-/**
- * @name github-script step without toJson hardening
- * @description Inline scripts passed to actions/github-script should use toJson when handling expression values.
- * @kind problem
- * @problem.severity recommendation
- * @precision medium
- * @id actions/custom/github-script-without-tojson
- * @tags actions
- *       security
- *       external/cwe/cwe-116
- */
-
-import actions
-
-from UsesStep step
-where step.getCallee() = "actions/github-script"
-select step,
-  "Review this github-script step for safe interpolation, validation, and least-privilege token use."

package/codeql/codeql-custom-queries-actions/queries/strict-external-action-pinning.ql

@@ -1,18 +0,0 @@
-/**
- * @name Uses step not pinned to a full commit SHA
- * @description Detects workflow/action `uses:` steps that are not pinned to a 40-character commit SHA.
- * @kind problem
- * @problem.severity warning
- * @precision high
- * @id actions/custom/strict-external-action-pinning
- * @tags actions
- *       security
- *       external/cwe/cwe-829
- */
-
-import actions
-
-from UsesStep uses
-where not uses.getVersion().regexpMatch("^[A-Fa-f0-9]{40}$")
-select uses,
-  "Action version is not pinned to a full commit SHA; review and pin to an immutable revision."

package/codeql/codeql-custom-queries-javascript/README.md

@@ -1,14 +0,0 @@
-# Custom CodeQL Queries (JavaScript / TypeScript)
-
-This pack adds repository-specific hardening checks for Node.js/TypeScript code.
-
-## Queries
-
-- `queries/child-process-shell-apis.ql`
-  - Flags `exec`/`execSync` usage outside tests.
-- `queries/innerhtml-assignment.ql`
-  - Flags assignment to `innerHTML` outside tests.
-
-## Why these checks
-
-These checks focus on high-signal security hotspots that often benefit from stricter review in extensions and tooling codebases.

package/codeql/codeql-custom-queries-javascript/codeql-pack.lock.yml

@@ -1,30 +0,0 @@
----
-lockVersion: 1.0.0
-dependencies:
-  codeql/concepts:
-    version: 0.0.15
-  codeql/controlflow:
-    version: 2.0.25
-  codeql/dataflow:
-    version: 2.0.25
-  codeql/javascript-all:
-    version: 2.6.21
-  codeql/mad:
-    version: 1.0.41
-  codeql/regex:
-    version: 1.0.41
-  codeql/ssa:
-    version: 2.0.17
-  codeql/threat-models:
-    version: 1.0.41
-  codeql/tutorial:
-    version: 1.0.41
-  codeql/typetracking:
-    version: 2.0.25
-  codeql/util:
-    version: 2.0.28
-  codeql/xml:
-    version: 1.0.41
-  codeql/yaml:
-    version: 1.0.41
-compiled: false

package/codeql/codeql-custom-queries-javascript/codeql-pack.yml

@@ -1,7 +0,0 @@
----
-library: false
-warnOnImplicitThis: false
-name: getting-started/codeql-extra-queries-javascript
-version: 1.0.0
-dependencies:
-  codeql/javascript-all: ^2.6.21

package/codeql/codeql-custom-queries-javascript/qlpack.yml

@@ -1,6 +0,0 @@
-library: false
-warnOnImplicitThis: false
-name: selfagency/beans-vscode-codeql-extra-queries-javascript
-version: 1.0.0
-dependencies:
-  codeql/javascript-all: ^2.6.21

package/codeql/codeql-custom-queries-javascript/queries/child-process-shell-apis.ql

@@ -1,26 +0,0 @@
-/**
- * @name Use of shell-based child_process APIs
- * @description Calls to exec/execSync run through a shell and are riskier than argument-array alternatives.
- * @kind problem
- * @problem.severity warning
- * @precision high
- * @id js/custom/child-process-shell-apis
- * @tags security
- *       external/cwe/cwe-078
- */
-
-import javascript
-
-private predicate inUserSource(InvokeExpr call) {
-  not call.getTopLevel().getFile().getRelativePath().regexpMatch("(^|.*/)(test|tests|__tests__|mocks?)/.*")
-}
-
-from CallExpr call
-where
-  inUserSource(call) and
-  not call.getCallee() instanceof PropAccess and
-  call.getCalleeName() = ["exec", "execSync"]
-select call,
-  "Shell-based process execution ($@) is harder to secure. Prefer execFile/spawn with argument arrays and strict input validation.",
-  call,
-  call.getCalleeName()

package/codeql/codeql-custom-queries-javascript/queries/innerhtml-assignment.ql

@@ -1,24 +0,0 @@
-/**
- * @name Assignment to innerHTML
- * @description Assigning to innerHTML can introduce XSS risk if any untrusted content reaches the sink.
- * @kind problem
- * @problem.severity warning
- * @precision medium
- * @id js/custom/innerhtml-assignment
- * @tags security
- *       external/cwe/cwe-079
- */
-
-import javascript
-
-private predicate inUserSource(AssignExpr assign) {
-  not assign.getTopLevel().getFile().getRelativePath().regexpMatch("(^|.*/)(test|tests|__tests__|mocks?)/.*")
-}
-
-from AssignExpr assign, PropAccess lhs
-where
-  inUserSource(assign) and
-  lhs = assign.getLhs() and
-  lhs.getPropertyName() = "innerHTML"
-select assign,
-  "Assignment to innerHTML can be unsafe. Prefer textContent or sanitization before rendering HTML."