Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/mcp-waits-for-busy-board.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@shivaedev/work-board": patch
---

### Fixed

- `work-board mcp` waits 30 seconds for a busy board instead of 10, so a Fleet view that takes most of its 25-second budget no longer reads as a stopped board. A board that does not answer in time is reported as busy, and an unreachable board as not reachable with the command that starts it.
4 changes: 3 additions & 1 deletion packages/work-board/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -567,7 +567,9 @@ claude mcp add --transport stdio work-board -- work-board mcp /absolute/path/to/
codex mcp add work-board -- work-board mcp /absolute/path/to/notes
```

Both commands require `work-board` on the client's PATH. `work-board mcp <dir>` reads the running board through `<dir>/board.sock`; it uses the same computed queries as the browser. If no board answers, every tool returns one error naming the directory and the `work-board <dir>` command to start it.
Both commands require `work-board` on the client's PATH. Without a global install, register `pnpm dlx @shivaedev/work-board mcp /absolute/path/to/notes`. Avoid `npx -y @shivaedev/work-board`: npm keeps its first install of the package, refuses to update that copy once a release pins another Effect version, and the server exits before the client connects.

`work-board mcp <dir>` reads the running board through `<dir>/board.sock`; it uses the same computed queries as the browser. The server starts and lists its tools whether or not a board runs, and each tool call reads the board when it runs, so a board that starts later answers the next call. A call waits for a busy board while its Fleet view finishes. If no board answers, the tool returns one error naming the directory and the `work-board <dir>` command to start it.

| Tool | Returns |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
Expand Down
4 changes: 3 additions & 1 deletion packages/work-board/src/server/diagnostics/daemon.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@ function makeDaemonClient() {
type DaemonClient = Effect.Success<ReturnType<typeof makeDaemonClient>>;

const FLEET_STOPPED = "Fleet isn't running, so agent work and its health are unknown.";
// A busy Fleet took up to 15 seconds for one read in measurement.
// A busy Fleet took up to 15 seconds for one read in measurement. Both reads of the Fleet view share one budget,
// so the Board answers inside the 30 seconds Claude Code's plugin fetch waits.
const FLEET_WAIT_SECONDS = 20;
export const FLEET_VIEW_MS = 25_000;

// npx runs the project's own @shivaedev/work-fleet, because the bare work-fleet command is rarely on PATH.
export function daemonUnavailable(error: unknown, port: number, folder: string): { readonly reason: string; readonly startCommand?: string } {
Expand Down
18 changes: 18 additions & 0 deletions packages/work-board/src/server/mcp.slow.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import { expect, vi } from "vitest";
import { boardStory, projectFiles } from "#test/boardStory.ts";
import { slowFleetDaemon } from "#test/workspaceBoardTraits.ts";

vi.setConfig({ testTimeout: 60_000 });

const project = projectFiles({ "one.md": "---\nid: one\nkind: task\nstatus: draft\n---\n# First task" });
const reported = { completed: [], items: [{ stage: "queued" as const, stageEnteredAt: 100, updatedAt: 200, workId: "one" }] };

boardStory.it(
"an agent's board_overview waits for a busy Fleet that answers after 15 seconds",
[project, slowFleetDaemon(reported, 15)],
function* ({ agentReads }) {
expect(yield* agentReads("board_overview")).toMatchObject({
fleet: { items: [expect.objectContaining({ stage: "queued", workId: "one" })], state: "ready" },
});
},
);
30 changes: 27 additions & 3 deletions packages/work-board/src/server/mcp.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ const withFleet = [
})),
];
const unavailable = { reason: "Fleet isn't set up for this Board.", state: "unavailable" };
const NO_BOARD = "error: No board answers in the project folder. Start one with: work-board 'the project folder'";
const NO_BOARD = "error: The Work Board in the project folder is not reachable. Start it with: work-board 'the project folder'";

boardStory.it("an agent connecting over MCP stdio finds three read-only tools", withFleet, function* ({ agentTools }) {
expect(yield* agentTools()).toEqual([
Expand All @@ -32,6 +32,18 @@ boardStory.it("an agent connecting over MCP stdio finds three read-only tools",
]);
});

boardStory.it(
"with no board running, an agent connecting over MCP stdio still finds the three tools",
[project, deferredServing],
function* ({ agentTools }) {
expect(yield* agentTools()).toEqual([
{ name: "board_overview", readOnly: true },
{ name: "item", readOnly: true },
{ name: "needs_you", readOnly: true },
]);
},
);

boardStory.it(
"board_overview reports the Fleet items, the goal counts and the Needs-you list the browser computes",
withFleet,
Expand Down Expand Up @@ -86,14 +98,26 @@ for (const [tool, args] of [
["item", { id: "task.first" }],
] as const) {
boardStory.it(
`with no board running, ${tool} answers one error that says how to start the board`,
`with no board running, ${tool} answers that the board is not reachable and how to start it`,
[project, deferredServing],
function* ({ agentReads }) {
expect(yield* agentReads(tool, args)).toBe(NO_BOARD);
},
);
}

boardStory.it(
"an agent that connected before the board started reads the board once it starts",
[project, deferredServing],
function* ({ agentReads, boardStarts }) {
expect(yield* agentReads("board_overview")).toBe(NO_BOARD);

yield* boardStarts();

expect(yield* agentReads("board_overview")).toEqual(expect.objectContaining({ fleet: expect.objectContaining(unavailable) }));
},
);

boardStory.it(
"without Fleet, board_overview and item say Fleet isn't set up instead of failing",
[project, boardWithoutFleet],
Expand Down Expand Up @@ -147,7 +171,7 @@ boardStory.it("item answers an error that names a missing item", [project, board
});

boardStory.it(
"after the board stops, an agent's next read says no board answers",
"after the board stops, an agent's next read says the board is not reachable",
[project, boardWithoutFleet],
function* ({ agentReads, boardStops }) {
expect(yield* agentReads("board_overview")).toEqual(expect.objectContaining({ fleet: expect.objectContaining(unavailable) }));
Expand Down
19 changes: 15 additions & 4 deletions packages/work-board/src/server/mcp/client.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
import { connect } from "node:net";
import { join } from "node:path";
import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
import { Effect, Layer, Schema } from "effect";
import { Cause, Effect, Layer, Schema } from "effect";
import { HttpClient, HttpClientRequest } from "effect/http";
import { RpcClient, RpcSerialization } from "effect/rpc";
import { RpcClientError } from "effect/rpc/RpcClientError";
import { errorMessage } from "#errorMessage.ts";
import { workContract } from "#rpc/contract.ts";
import { FLEET_VIEW_MS } from "#server/diagnostics/daemon.ts";
import { RPC_PATH } from "#server/http/rpcPolicy.ts";

export class BoardToolError extends Schema.TaggedError<BoardToolError>()("BoardToolError", { message: Schema.String }) {}
Expand All @@ -16,9 +17,19 @@ function makeClient() {
}
export type BoardClient = Effect.Success<ReturnType<typeof makeClient>>;

// The Board's Fleet view alone may take its whole budget, and the Board's own index and document reads come on top.
const BOARD_WAIT_SECONDS = FLEET_VIEW_MS / 1000 + 5;

function toolError(directory: string, error: unknown) {
if (error instanceof RpcClientError || (error instanceof Error && "_tag" in error && error._tag === "TimeoutError")) {
return new BoardToolError({ message: `No board answers in ${directory}. Start one with: work-board '${directory.replaceAll("'", "'\\''")}'` });
if (Cause.isTimeoutError(error)) {
return new BoardToolError({
message: `The Work Board in ${directory} did not answer within ${BOARD_WAIT_SECONDS} seconds. It may be busy; try again.`,
});
}
if (error instanceof RpcClientError) {
return new BoardToolError({
message: `The Work Board in ${directory} is not reachable. Start it with: work-board '${directory.replaceAll("'", "'\\''")}'`,
});
}
return new BoardToolError({ message: errorMessage(error) });
}
Expand All @@ -38,7 +49,7 @@ export function readBoard<A, E>(directory: string, read: (client: BoardClient) =
}).pipe(Layer.provide([http, RpcSerialization.layerNdjson]));
return Effect.scoped(Effect.flatMap(makeClient(), read)).pipe(
Effect.provide(protocol),
Effect.timeout("10 seconds"),
Effect.timeout(`${BOARD_WAIT_SECONDS} seconds`),
Effect.mapError((error) => toolError(directory, error)),
);
}
5 changes: 1 addition & 4 deletions packages/work-board/src/server/views/fleetItems.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { laneOf } from "#browser/views/now.ts";
import { DAEMON_PORT } from "#diagnostics/daemonContract.ts";
import { inboxItems } from "#server/attention/inbox.ts";
import { requestInbox } from "#server/attention/requestInbox.ts";
import { daemonUnavailable, readDaemon } from "#server/diagnostics/daemon.ts";
import { daemonUnavailable, FLEET_VIEW_MS, readDaemon } from "#server/diagnostics/daemon.ts";
import { fleetChecksBrief } from "#server/document/briefDiagnostic.ts";
import { itemRequests } from "#server/document/requests.ts";
import type { Snapshot } from "#server/search/snapshot.ts";
Expand Down Expand Up @@ -39,9 +39,6 @@ const fleetItemsUnavailable = Effect.fn("WorkBoard.fleetItemsUnavailable")(funct
return projection;
});

// Both Fleet reads share one budget, so the Board answers inside the 30 seconds Claude Code's plugin fetch waits.
const FLEET_VIEW_MS = 25_000;

export function fleetItems(folder: string, fleetPort: number | null = DAEMON_PORT): Effect.Effect<FleetItemsProjection, never, Workspace> {
if (fleetPort === null) {
return fleetItemsUnavailable({ reason: "Fleet isn't set up for this Board." });
Expand Down
2 changes: 1 addition & 1 deletion packages/work-board/src/test-support/mcpClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ export const mcpClient = Effect.fn("Test.mcpClient")(function* (directory: strin
pending.set(id, { reject, resolve });
child.stdin.write(`${JSON.stringify({ id, jsonrpc: "2.0", method, params })}\n`);
}),
).pipe(Effect.timeout("15 seconds"));
).pipe(Effect.timeout("45 seconds"));
}
yield* send("initialize", { capabilities: {}, clientInfo: { name: "board-test", version: "1" }, protocolVersion: "2025-11-25" });
child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
Expand Down
Loading