examples/MCP-tools Public
Map the architecture and the tool-call flow
system.yaml names the Worker, the tools library, the USAGE namespace and the two packages they import, so rebasely arch check can hold the map to the code. The flows walk through one agent calling time_in_zone end to end and someone reading /stats.
Changed files
4 files changed65 additions0 deletionsagainst d0ed32f
Added.rebasely/architecture/flows/tool-call.yaml+20−0
| @@ -0,0 +1,20 @@ | ||
| +title: An agent calling a tool | ||
| +description: >- | ||
| + A model asks for the time in Tokyo. Its MCP client connects, lists the tools and calls | ||
| + time_in_zone. Every message is its own POST to /mcp, answered by a fresh server. | ||
| +actors: [agent, mcp-client] | ||
| +steps: | ||
| + - { from: agent, to: mcp-client, label: "needs the current time in Tokyo" } | ||
| + - { from: mcp-client, to: mcp-server, label: "POST /mcp: initialize" } | ||
| + - { from: mcp-server, to: mcp-client, label: server info and the tools capability } | ||
| + - { from: mcp-client, to: mcp-server, label: "POST /mcp: tools/list" } | ||
| + - { from: mcp-server, to: tools, label: "read each tool's name, description and schemas" } | ||
| + - { from: mcp-server, to: mcp-client, label: three tools with JSON Schema inputs and outputs } | ||
| + - { from: agent, to: mcp-client, label: "call time_in_zone with zone tokyo" } | ||
| + - { from: mcp-client, to: mcp-server, label: "POST /mcp: tools/call time_in_zone" } | ||
| + - { from: mcp-server, to: mcp-sdk, label: check the arguments against the input schema } | ||
| + - { from: mcp-server, to: tools, label: "run it: resolve tokyo to Asia/Tokyo, read the offset" } | ||
| + - { from: tools, to: mcp-server, label: "local time, or a ToolError saying what to fix" } | ||
| + - { from: mcp-server, to: mcp-client, label: "structuredContent and JSON text, isError on failure" } | ||
| + - { from: mcp-server, to: usage, label: "count the call for today, after the response" } | ||
| + - { from: mcp-client, to: agent, label: the result as a tool message } | ||
Added.rebasely/architecture/flows/usage-stats.yaml+7−0
| @@ -0,0 +1,7 @@ | ||
| +title: Reading usage stats | ||
| +description: Someone checks which tools get called and how often they fail. | ||
| +actors: [browser] | ||
| +steps: | ||
| + - { from: browser, to: mcp-server, label: "GET /stats?days=7" } | ||
| + - { from: mcp-server, to: usage, label: "list calls:<day>: once per day, counts from key metadata" } | ||
| + - { from: mcp-server, to: browser, label: "calls and errors per tool per day, newest first" } | ||
Added.rebasely/architecture/system.yaml+36−0
| @@ -0,0 +1,36 @@ | ||
| +components: | ||
| + mcp-server: | ||
| + kind: worker | ||
| + description: >- | ||
| + The Worker. Serves MCP over Streamable HTTP at /mcp, statelessly: each POST gets a fresh | ||
| + McpServer with every tool registered. Also counts tool calls and serves them at /stats. | ||
| + owns: | ||
| + - src/index.ts | ||
| + - src/worker.ts | ||
| + - src/server.ts | ||
| + - src/usage.ts | ||
| + talks_to: | ||
| + - { to: tools, via: import } | ||
| + - { to: mcp-sdk, via: import } | ||
| + - { to: usage, via: kv } | ||
| + tools: | ||
| + kind: library | ||
| + description: >- | ||
| + The tools themselves: a name, a description written for models, zod input and output | ||
| + schemas and a pure run function each. No MCP, HTTP or bindings in here. | ||
| + owns: | ||
| + - src/tools/** | ||
| + talks_to: | ||
| + - { to: zod, via: import } | ||
| + usage: | ||
| + kind: kv | ||
| + description: Calls and errors per tool per UTC day, kept 90 days. Approximate by design. | ||
| + binding: USAGE | ||
| + mcp-sdk: | ||
| + kind: external | ||
| + description: The MCP TypeScript SDK. McpServer validates arguments and builds results; the Web-standard transport speaks Streamable HTTP. | ||
| + package: "@modelcontextprotocol/sdk" | ||
| + zod: | ||
| + kind: external | ||
| + description: Schema library for tool inputs and outputs. The SDK turns the schemas into JSON Schema for tools/list. | ||
| + package: zod | ||
Added.rebasely/architecture/views/runtime.yaml+2−0
| @@ -0,0 +1,2 @@ | ||
| +description: What runs on Cloudflare and the storage it touches, without the libraries. | ||
| +components: [mcp-server, tools, usage] | ||
Checks
No checks reported for this commit.
Runs
No runs for this commit.