CSE Roadmap

Core tier · about 9 hours · 13 parts

Part 2 of 13 · 6 min read

Put the rule where a plain function call can reach it

Put the rule where a plain function call can reach it

A restaurant kitchen puts the grill in one place and the till in another, so a cook can test a new sauce without a customer standing there. The server is split the same way, and almost every testing decision follows from the split.

In plain words: a business rule belongs in the layer that can be tested with a plain function call, not in the layer that only runs through the protocol.

Layer Files What it knows How it is tested
Data and rules db.py, service.py tickets, who may see what, the state machine (open, closed), idempotency plain function calls, no MCP at all
Tool adapter tools.py names, descriptions, schemas, how a rule's failure becomes words for a model lint, snapshot, protocol checks
Transport and identity app.py, stdio_main.py, world.py how bytes arrive, who is calling child process, real socket, tokens

"Closing a closed ticket is an error" is a business rule, so it lives in Desk.close, and a one-line unit test pins it there — no server, no JSON, no network:

# from code/mini-build/service.py
def close(self, user: str, ticket_id: int, resolution: str) -> dict:
    self._staff(user, "close tickets")
    r = self._visible(user, self._get_row(ticket_id), ticket_id)
    if r["status"] == "closed" and "close_closed_ok" not in self.bugs:
        raise DeskError("BAD_STATE", f"Ticket {ticket_id} is already closed (resolution: {r['resolution']!r}).",
                        f"If it needs more work, call `ticket_reopen` with ticket_id {ticket_id}. Otherwise do nothing.")

Read it as: the rule itself (closed tickets reject a second close) and the help it offers (call ticket_reopen) are decided here, with no knowledge that MCP exists. Suppose the rule lived in tools.py instead. Then the only way to test it would be a full tool call through the protocol. That is slower to run and harder to read when it fails.

Service layer, adapter layer

The service layer is the code that enforces the business rules and knows nothing about the protocol carrying them. The adapter layer turns a rule's success or failure into the words, schema and error shape a protocol client expects. Example: Desk.close is the service; tools.py's wrap(...) around it, which turns a raised DeskError into an isError result, is the adapter.

The database does some of the work too: the schema has CHECK constraints on status and priority, and a unique index on the idempotency key. A constraint is a test that runs on every write, in production. Part 5 below shows a defect that only a database constraint can really prevent.

There are three kinds of user. (Module 5's authorization server issues them tokens.) A customer (carol) may read and comment on her own tickets. Support staff (alice) may do everything on any ticket. An administrator (dave) may also export. Two layers enforce this, on purpose. The token's scopes (tickets:read, tickets:write, desk:admin) are checked before the tool runs. The service then checks the record (is this ticket yours?). Part 10 shows a case where only the second layer stands between a customer and a closed ticket.

The tool surface

Eight tools, each with one job:

Tool Reads or writes Needs
tickets_search reads tickets:read
ticket_get reads tickets:read
ticket_create writes (idempotent) tickets:write
ticket_comment writes tickets:write
ticket_close, ticket_reopen, ticket_assign writes, staff only tickets:write
desk_export reads everything, admin only desk:admin

The design rules come from module 1; here is how they show up in this server.

Descriptions say what, when and what comes back. Every description has three parts: what the tool does, when to use it (and often when to use another tool instead), and what it returns. For example, ticket_close reads: "Close an open ticket with a one-sentence resolution. Staff only. Use this when the problem is solved or answered; to undo it call ticket_reopen. Returns the closed ticket." Naming the neighbouring tool is deliberate: it tells the model where to go next, and the lint rule in part 6 checks that each description contains a "Use this ..." sentence and a "Returns ..." sentence.

Every parameter is described, and closed sets are enums. priority is low, normal, high or urgent in the schema, so a misspelling is rejected by the schema before any code runs. additionalProperties: false means a misspelled argument name is an error, not silently ignored. (For a tool with no parameters, the specification recommends exactly {"type": "object", "additionalProperties": false}.)

Results have an outputSchema. The specification says that if a server declares one it must return structured results that match it, and that clients should validate. It also asks that a tool returning structured content should also return the same JSON as text, for older clients. The example's conformance suite checks both. The output schemas are closed too (no extra fields), which is how a leaked field gets noticed (part 7).

Annotations are honest, and a test checks them. readOnlyHint is true for three tools and false for the rest. The specification warns that clients must treat annotations as untrusted unless the server is trusted, so an annotation is a claim, and a claim can be tested: the suite calls every tool marked read-only and checks that the database did not change.

Writes that can be retried take an idempotency key. ticket_create accepts a key; sending the same key again returns the same ticket and created: false. Module 4 showed the same idea for one-time actions. Part 5 below shows why one caller retrying twice is not the same test as six callers retrying at once.

Lists are paged, and capped. tickets_search returns at most 20 tickets, with total and a next_cursor. One tool does not follow this rule, and the example leaves it that way on purpose: desk_export returns everything, which is the subject of part 13.

Design choices, and where the specification is silent

  • Listing is the same for everyone. The specification allows tools/list to vary by the authorization presented (for example, hiding tools the caller's scopes cannot use) but forbids varying it per connection or as a side effect of other requests. The server lists all 8 tools to every caller and lets a call fail with 403. Hiding tools is a reasonable alternative (Medium exercise 1 touches on it).
  • No per-ticket resources. The resources and prompts in the example (a policy text and a triage prompt) are public. The example does not expose desk://tickets/{id} as a resource, because the server's resource handler has no caller identity, so it could not apply the ownership rule. A resource that bypasses your access control is a hole, not a convenience.
  • Tool names follow the example's own house rule (lower snake case, 3 to 41 characters). The specification is looser: names should be 1 to 128 characters from letters, digits, underscore, hyphen and dot, and unique within a server.