Skip to main content

Setup

Get a Logic Bee API workspace ready so coding-agent skills can run.

Outcome​

MCP tools are visible in the client. A slash name starts one skill.

Assumptions​

  • You work in a Logic Bee API repo, not in this documentation repo.
  • The repo contains .agents/skills/, .agents/rules/catalog.md, and scripts/mcp/server.ts.
  • This site does not host the skill files.

Prerequisites​

  • Installation: Git, Node.js 22.x or newer, pnpm 10.x, clone, .env, pnpm i
  • A client that can spawn a local stdio MCP server (Cursor, Claude Code, or another stdio client)
  • tar on PATH when a packaged SQLite index must unpack from .logic/*.tar.gz

Goal​

Register the logic-bee MCP server. Rebuild workspace indexes. Confirm a skill starts.

Procedure​

1. Open the Logic Bee workspace​

Open the Logic Bee API repository in the client.

Confirm these paths exist:

  • .agents/skills/logic-discovery/SKILL.md
  • .agents/rules/catalog.md
  • scripts/mcp/server.ts

2. Confirm Node and the install​

From the repo root:

node -v
pnpm -v

Expected result: Node.js 22.x or newer. pnpm 10.x.

If node_modules is missing, run pnpm i.

Native module better-sqlite3 must match this Node. hook_graph search and impact need FTS5.

3. Rebuild workspace indexes​

warning

pnpm update-workspace writes generated files. Run it from the repo root before the first MCP call.

pnpm update-workspace

Expected result: Exit code 0. Interface registry, hook barrels, canonical imports, and the hook-graph index rebuild.

4. Confirm MCP registration​

The client must spawn the server with this workspace as cwd.

Checked-in files:

FileTypical command
.mcp.jsonnode --import tsx scripts/mcp/server.ts
.cursor/mcp.jsonthe same server entry, sometimes through a shell wrapper

Equivalent: npx tsx scripts/mcp/server.ts.

The registration key is logic-bee in the checked-in files. Some clients also use bobWorkspace. The server internal name stays logic-bee.

If you register the server in a user-scoped file, set an absolute cwd to this repo.

5. Enable the server in the client​

  1. Open MCP settings in the client.
  2. Enable logic-bee or bobWorkspace.
  3. Refresh MCP, or reload the window.
warning

If the tools are not visible, stop. Do not grep the tree for catalogs MCP owns.

Expected result: The session lists logic-bee tools, including flow_documents and hook_graph.

6. Ping MCP​

After tools are visible, a skill preflight calls:

flow_documents { op: "list" }

For hook work, the skill also calls hook_graph { op: "stats" }.

Do not run npx tsx scripts/logic-bee-*.ts as a substitute. Do not pipe JSON-RPC in the shell.

Most tools do not need .env. query_db and list_collections need Mongo Atlas variables in the project-root .env. Do not open .env to diagnose a tool error.

7. Start a skill​

/logic-discovery

If the slash name does not start the skill, put the file on line 1:

@.agents/skills/logic-discovery/SKILL.md

Load rules by exact path from .agents/rules/catalog.md. Do not glob .agents/rules/.

Expected result: The skill asks for type if type is missing, or it starts a broad MCP sweep.

Verification​

  1. node -v reports 22.x or newer.
  2. pnpm update-workspace exits 0.
  3. An MCP json file exists.
  4. The client shows logic-bee tools.
  5. /logic-discovery starts, or the @.agents/skills/logic-discovery/SKILL.md path starts.

Recovery​

SymptomDiagnosisResolution
Tools are not in the sessionMCP json, cwd, or client cacheConfirm the server command and cwd. Enable the server. Refresh MCP.
NODE_MODULE_VERSION or missing better-sqlite3 bindingsNative module built for another NodeUse Node 22.x. Run pnpm i, then pnpm rebuild better-sqlite3.
project_graph index not foundNo CFP project indexNeed .logic-index/project-index.db or .logic/project-index.tar.gz. MCP cannot create that index.
query_db or list_collections fails on envMongo variables missingGet a project-root .env from the team. Do not read .env in the agent.
Skill greps apps/api/src/app/hooks for MCP factsTools missing and the agent fell backStop. Fix MCP. Call the skill again.