sorftime-mcp AGENTS.md

Codex project instructions

This file is the authoritative development guide for coding agents working in this repository. The root README.md is written for repository users and operators; it is not a substitute for these instructions.

Mission

Maintain a governed Sorftime data service with one deterministic API core and three adapters:

• MCP is the team-facing execution, identity, audit, rate-limit, and policy boundary;
• the Sorftime Research Skill is the Host-side routing and interpretation protocol;
• the CLI is the administrator/developer surface for complete endpoint access, diagnostics, batch work, and emergency operations.

Probabilistic language understanding must end before endpoint authorization and execution begin.

Start here

Read the smallest relevant set before changing code:

• architecture or adapter boundaries: docs/architecture.md;
• MCP/Skill behavior: docs/mcp-skill-integration.md and skills/sorftime-research/SKILL.md;
• deployment, authentication, secrets, or production readiness: docs/deployment.md;
• endpoint contracts: src/endpoints.ts and src/core/governance.ts;
• MCP tools: src/mcp/server.ts;
• CLI behavior: README.md and src/cli.ts.

Compatibility baseline

• package, MCP contract, and governance policy: 1.0.0;
• endpoint registry: 52 Sorftime endpoints;
• ordinary MCP surface: 4 tools, free and read-only only;
• optional admin MCP surface: 2 tools, still free and read-only;
• Skill: sorftime-research, compatible with MCP 1.0.x;
• runtime: Node.js 20+, TypeScript, MCP SDK v1, Streamable HTTP and stdio.

Non-negotiable invariants

1. Never commit or print a real Sorftime Account-SK, MCP API key, proxy secret, Authorization header, or raw credential file.
2. src/core/governance.ts must classify all 52 endpoints. MCP authorization never parses the human cost string.
3. The initial MCP policy exposes only billing=free, effect=read, explicitly allowlisted endpoints.
4. Paid reads, Coin-charged calls, task creation, updates, subscriptions, and deletes are not MCP tools.
5. MCP never exposes raw_call or arbitrary endpoint/body passthrough. Raw access remains CLI-only for operators.
6. User/tenant/role identity comes only from authenticated transport context. Tool inputs must never select or override identity.
7. Stdio has no employee authentication; bind one principal at process launch and document it as local/operator mode.
8. Audit records may contain actor, tenant, tool, endpoint names, marketplace, fingerprints, timing, decision, and outcome. They must not contain complete arguments, keywords, ASIN lists, headers, tokens, or upstream payloads.
9. A free endpoint reporting positive RequestConsumed opens the billing circuit. Do not continue automatically.
10. MCP retries remain zero. A lost response must not duplicate paid work; paid work is unavailable in MCP regardless.
11. Preserve exact documented wire casing (ASIN, Asin, Asins, Querystartdt). Do not normalize payload keys at the shared-client boundary.
12. Upstream unknown schemas remain JSON. Do not invent field meanings or present missing/unavailable values as zero.
13. Shared quota is account-global, never an employee allowance. Per-person activity comes from MCP audit, not Sorftime balance fields.
14. The Skill must not invoke the CLI, request credentials, invent identifiers, silently substitute stale monitoring for paid realtime data, or infer causality.
15. CLI completeness must not weaken MCP policy. CLI and MCP share the API core, not the same public command surface.
16. HTTP production/non-loopback mode must authenticate, restrict Hosts, validate Origins when present, cap sessions/concurrency, and keep the Account-SK server-side.
17. MCP output and errors must remain sanitized. Unexpected upstream payloads never appear in public error details.
18. Do not add experimental MCP Tasks for Sorftime async APIs until ownership, identity binding, TTL, persistence, and polling policy are designed and tested.