README.md

mcp-server/README.md

1. # Meridian Orders MCP server
3. A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server
4. over Plinth, Meridian Display Co.'s order system (both fictional; see the
5. [root README](../README.md)). It is built to be **hosted on Cloudflare
6. Workers** so the whole company can share one remote server, with a stdio entry
7. for local use.
9. > **Status:** all six read tools are implemented. Live requests are **gated
10. > off** by default: nothing reaches production until
11. > `PLINTH_ALLOW_LIVE_REQUESTS=true` and an API key are both set.
13. ## Two runtimes, one core
15. The tool set and the Plinth client are runtime-agnostic (Web-standard
16. `fetch`/`URL` only, with config injected and no `process.env` in the core). Two
17. thin entry points adapt it to each runtime:
19. | Entry | Transport | Use |
20. | --- | --- | --- |
21. | `src/index.ts` | stdio | **Local**: exercise the tools from a desktop MCP client. |
22. | `src/worker.ts` | Streamable HTTP + SSE | **Hosted (Cloudflare Workers)**: the company-wide deployment. |
24. Both call the same `registerTools()` in `src/server.ts`, so behavior is
25. identical across runtimes.
27. ### Why Cloudflare Workers
29. - One hosted URL the whole company connects to, with no per-person setup.
30. - The Plinth client already uses only Web-standard APIs, so it runs on the V8
31. isolate unchanged.
32. - Sessions run as Durable Objects (`McpAgent`), which gives the shared rate
33. limiter (10 requests / 10 s) a natural home, and later OAuth-based access
34. control.
36. ## Safety
38. The Plinth API is **production-only (no sandbox)** and the key has **global
39. read scope**. So:
41. - only the six **read** methods are registered; the write methods are absent;
42. - a four-layer failsafe (`src/lib/guard.ts`) makes a write impossible to
43. dispatch, even through the passthrough tools;
44. - `plinthRequest()` refuses to run unless `PLINTH_ALLOW_LIVE_REQUESTS=true`
45. **and** a key are set.
47. ## Layout
49. ```
50. src/
51. ├── index.ts # Node/stdio entry (local)
52. ├── worker.ts # Cloudflare Workers entry (McpAgent, remote HTTP)
53. ├── env.ts # Workers env bindings (Env)
54. ├── server.ts # registerTools() + createServer(), shared and runtime-agnostic
55. ├── rateLimiterDO.ts # the shared rate-limiter Durable Object
56. ├── tools/
57. │ ├── index.ts # read-only tool registry
58. │ ├── types.ts # ToolModule / ToolContext / ToolResult
59. │ ├── getOrders.ts
60. │ ├── getStatusCatalog.ts
61. │ ├── getCustomers.ts
62. │ ├── getSplitShipments.ts
63. │ ├── getProduct.ts # unprobed: passthrough params
64. │ └── getInventory.ts # unprobed: passthrough params
65. └── lib/
66. ├── config.ts # configFromEnv() (injected) + live-request gate
67. ├── http.ts # buildUrl + plinthRequest(ctx, …), gated
68. ├── guard.ts # the write-prevention failsafe
69. ├── rateLimit.ts # reserveSlot() scheduler + in-memory limiter
70. ├── errors.ts # Config / PlinthApi / RateLimit
71. ├── collections.ts # [] vs "1".."N" normalization; numeric coercion
72. ├── dates.ts # ISO -> yyyymmdd request format
73. ├── orderNumber.ts # MD2639582 -> order_ref resolution
74. └── classification.ts # sensitivity classes (not wired yet)
76. verify/ # offline checks of the failsafe and the rate limiter
77. test/ # node --test unit tests for collections, dates, orderNumber
78. tsconfig.json # Node core + build (excludes worker: Node globals)
79. tsconfig.worker.json # Worker + shared core (Workers globals)
80. wrangler.jsonc # Cloudflare config (DO bindings, vars, compat flags)
81. ```
83. Node and Workers global types conflict, so each runtime has its own tsconfig
84. over a shared `tsconfig.base.json`. The shared core typechecks under both.
86. ## Tools (all read-only)
88. | Tool | Plinth method | Notes |
89. | --- | --- | --- |
90. | `get_orders` | `orders.fetch` | order/batch lookup |
91. | `get_status_catalog` | `statuses.list` | status catalog (lookup table) |
92. | `get_customers` | `customers.fetch` | email / date range; **no phone filter** |
93. | `get_split_shipments` | `orders.splitShipments` | bare-array response |
94. | `get_product` | `products.fetch` | **unprobed**, passthrough params |
95. | `get_inventory` | `inventory.fetch` | **unprobed**, passthrough params |
97. The write methods `orders.setStatus` and `inventory.adjust` are **out of
98. scope** and not implemented. Adding write capability needs explicit sign-off
99. from the owner and whoever maintains Plinth.
101. ## Develop
103. ```bash
104. cd mcp-server
105. npm install
106. npm run typecheck:all # node core + worker
107. npm test # build, then the offline checks and unit tests below
108. ```
110. `npm test` builds `dist/` and runs `verify/failsafe.mjs` (the failsafe blocks
111. every write path), `verify/ratelimit.mjs` (the limiter paces bursts) and the
112. unit tests in `test/`. None of them touch the network. CI
113. (`.github/workflows/ci.yml`) runs the typecheck, the tests and
114. `wrangler deploy --dry-run` on every push.
116. ### Local (stdio)
118. ```bash
119. npm run dev
120. ```
122. ### Local (Workers, via Wrangler)
124. ```bash
125. cp .dev.vars.example .dev.vars # fill in PLINTH_API_KEY locally (gitignored)
126. npm run dev:worker # http://localhost:8787/mcp (needs Node 22+)
127. ```
129. ## Deploy to Cloudflare
131. ```bash
132. wrangler secret put PLINTH_API_KEY # never commit the key
133. npm run deploy
134. ```
136. `wrangler.jsonc` declares the `PlinthMcp` and `RateLimiterDO` Durable Objects and
137. the non-secret vars (`PLINTH_API_BASE_URL`, `PLINTH_ALLOW_LIVE_REQUESTS`). Check
138. the build any time with:
140. ```bash
141. npx wrangler deploy --dry-run
142. ```
144. ## Next steps
146. 1. **Company-wide access control.** `src/worker.ts` is unauthenticated. Front
147. it with OAuth (`@cloudflare/workers-oauth-provider`) or Cloudflare Access,
148. and thread the verified identity into `ToolContext` so
149. `lib/classification.ts` can enforce per-customer scoping and PII redaction.
150. The API provides none.
151. 2. Probe `products.fetch` / `inventory.fetch` and replace their passthrough
152. schemas.
154. The API reference lives at [`../docs/PLINTH-API.md`](../docs/PLINTH-API.md).