@selfagency/beans-mcp 0.1.2 → 0.1.3

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.

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

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

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * @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

@@ -0,0 +1,18 @@
+/**
+ * @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

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

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * @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

@@ -0,0 +1,24 @@
+/**
+ * @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."

package/dist/README.md

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