AGENTS.md

1# mcp-stdio-core -- JSON-RPC stdio Framing + Dispatch (Core)
2 
3**Generated:** 2026-07-17 / 7d664b96b
4 
5## OVERVIEW
6 
7The lowest-level core package: JSON-RPC 2.0 transport over stdio (line-mode and Content-Length framed), an event-loop server with idle timeout, response builders, and an `isPlainRecord` guard. Zero runtime/peer dependencies; imports nothing from the workspace, consumed by every MCP-layer package. Package: `@oh-my-opencode/mcp-stdio-core`.
8 
9## KEY FILES (5 source, all flat in `src/`)
10 
11| File | Subpath export | Role |
12|------|----------------|------|
13| `types.ts` | `./types` | `JsonRpcId/Error/Result/Response`, `McpToolDescriptor`, `TextContent`, `McpLifecycleLog` |
14| `record.ts` | `./record` | `isPlainRecord(value)` type guard |
15| `responses.ts` | `./responses` | `successResponse`, `errorResponse`, `jsonRpcId`, `messageFromError` |
16| `server.ts` | `./server` | `runJsonRpcStdioServer(config)`: async-generator loop, idle timeout, `McpRequestHandler`, exits on terminal output errors |
17| `transport.ts` | `./transport` | `readStdioJsonRpcMessages` (async gen), `writeStdioJsonRpcResponse`, dual framing |
18 
19## CONSUMERS
20 
21- `lsp-core/src/mcp.ts` (primary): LSP MCP server.
22- `git-bash-mcp/src/mcp.ts`: Git Bash MCP server.
23- `lsp-daemon/src/proxy.ts`: stdio MCP proxy (also imports the `./record` subpath).
24 
25## NOTES
26 
27- **Two framing modes:** `"line"` (`\n`-delimited) and `"framed"` (`Content-Length:` header per MCP spec); auto-detected by scanning the buffer prefix for `content-length:`.
28- **Idle timeout uses `timer.unref()`**: the timeout never keeps the process alive.
29- **Handler contract:** return `undefined` to skip silently; `onHandlerError` catches exceptions; `parseErrorResponse` customizes JSON parse errors.
30- **Output writes are awaited; closed output stops the loop:** `writeStdioJsonRpcResponse` is async and `writeChunk` removes its one-shot `error` listener after settle. `writeResponse` catches terminal output errors (`EPIPE`, `ERR_STREAM_DESTROYED`, `ERR_STREAM_WRITE_AFTER_END`), logs `output_error`, and returns false so the read loop exits; non-terminal write errors still propagate.
31- **Keep zero dependencies.** `.js` suffix on relative imports (ESM). This is the floor of the package layering; it must stay leaf.
32- Parent: [`packages/AGENTS.md`](../AGENTS.md).
33