now-sdk-ext-mcp: Instructions file for Codex

AGENTS.md

Operating rules for automated agents working in this repository.

For architecture, layout and build commands, read CLAUDE.md. This file is only about the things that will bite you here and not elsewhere.

---

What this repository is

An MCP server exposing ~86 ServiceNow tools to AI agents. It is launched as a non-interactive child process, speaks JSON-RPC over stdio, and acts against real instances with the launching user's credentials.

Two things follow, and both are unusual enough to be worth stating:

• stdout is a protocol channel, not an output channel.
• The caller is a model, not a person. Tool descriptions and result text are the entire interface. Prose here is not documentation about the product; it is the product.

---

Hard rules

1. Never write to stdout

console.log, a stray print, a library that logs on import — any byte on stdout that is not JSON-RPC corrupts the stream and breaks the client's parser, usually with an error that points nowhere near the cause.

Diagnostics go to stderr, always:

console.error("[thing] message");

This is why credstore-boot.ts uses process.stderr.write and why the progress helper swallows notification failures to stderr rather than surfacing them.

2. A tool's description is its implementation, as far as the model is concerned

Tools are hand-registered with a title, a description, and a zod inputSchema. The model never reads the handler. If the description does not say that a flow with approval steps must run in background mode, the model will not know.

Two patterns already in the codebase, both worth continuing:

• Explain the platform, not just the parameter. execute_script's description covers scoped-vs-global name qualification with concrete examples, because that is the thing callers actually get wrong.
• Put next steps in the RESULT, especially on empty and error paths. "No tables found in this search group. Use \add_code_search_table` to add tables."` costs nothing until the model is stuck, and is how chains self-correct without bloating every description.