S3WORM MCP Server

@decoperations/s3worm-mcp is a Model Context Protocol server that exposes the @decoperations/s3worm CLI as structured tools and resources for editors and agents (Claude Code, Cursor, Smithery, etc.).

It runs over stdio and shells out to pnpm --filter @decoperations/s3worm exec worm inside a workspace root that the host process configures via environment variables.

Install

The package is part of this monorepo and currently "private": true (no registry publish). Use the bundled build:

pnpm --filter @decoperations/s3worm-mcp build
# binary at: packages/s3worm-mcp/dist/index.js

Two ready-made host configs ship with the repo and both point at node packages/s3worm-mcp/dist/index.js:

Host	Config file
Generic MCP host	`.mcp.json`
Cursor	`.cursor/mcp.json`

Configuration

The server reads three environment variables:

Env var	Default	Purpose
`S3WORM_MCP_WORKSPACE_ROOT`	`process.cwd()`	Monorepo root the server runs `worm` against. Resolved relative to cwd if not absolute.
`WORM_ROOT`	`.worm` under workspace	Location of `schema.json` and rules. Honors absolute paths.
`S3WORM_MCP_ALLOW_OUTSIDE_OUTPUT`	unset	When `1`, `worm_codegen` may write to paths outside the workspace. Off by default.

Tools

The server registers four tools. All tool output is plain text wrapped in MCP text content blocks.

`worm_lint`

No arguments. Runs worm lint in the workspace root and returns the combined exit code plus stdout/stderr.

OK (exit 0)
✓ schema valid
✓ 3 rules pass

`worm_read_schema`

No arguments. Reads .worm/schema.json from the resolved WORM_ROOT and returns a four-line summary:

schemaVersion: 1.0
sourceOfTruth: schema.json
models (3): User, Post, Comment
paths (2): /users/:id; /posts/:id

If no schema is present, returns No schema at <path>.

`worm_codegen`

Arguments:

{
  outputDir: string;   // workspace-relative
  zod?: boolean;       // also emit Zod schemas
}

Runs worm codegen --output <dir> (optionally --zod). Refuses output paths outside the workspace unless S3WORM_MCP_ALLOW_OUTSIDE_OUTPUT=1.

`worm_llms`

No arguments. Returns the canonical concise llms.txt content for @decoperations/s3worm — the same text the CLI's worm llms command emits.

Resources

URI	MIME	What it is
`s3worm://llms/concise`	`text/plain`	Canonical concise `llms.txt` for the SDK.
`s3worm://worm/schema`	`application/json`	Raw `.worm/schema.json` from the workspace (text fallback if missing).

Safety

worm_codegen resolves outputDir against the workspace and rejects paths that escape it. Mirror of isPathInsideWorkspace. Override only with S3WORM_MCP_ALLOW_OUTSIDE_OUTPUT=1.
The server shells out to pnpm; the host process must have pnpm on PATH.
The MCP framing uses stdio. Diagnostics inside the server go to stderr only — console.log would corrupt the framing.

Development

pnpm --filter @decoperations/s3worm-mcp dev        # tsup watch
pnpm --filter @decoperations/s3worm-mcp test       # vitest
pnpm --filter @decoperations/s3worm-mcp typecheck  # tsc --noEmit
pnpm --filter @decoperations/s3worm-mcp lint       # eslint