1feature:
 2  name: server
 3  product: cooked-mcp
 4  description: Start Cooked as a single-user MCP server over stdio or local HTTP.
 5
 6components:
 7  IDENTITY:
 8    requirements:
 9      1: The MCP server identifies itself as Cooked.
10      2: The command starts the MCP server without requiring subcommands.
11  TRANSPORT:
12    requirements:
13      1: The server starts with stdio transport by default.
14      2: The server accepts an explicit transport selection through a --transport flag.
15      2-1: The --transport stdio value selects stdio transport.
16      2-2: The --transport http value selects Streamable HTTP.
17      3: HTTP transport listens on a configurable address.
18      3-1: HTTP transport defaults to 127.0.0.1:8123.
19      4: The server rejects unknown transport selections before serving.
20      5: HTTP transport serves MCP requests at /mcp.
21  CONFIG:
22    requirements:
23      1: The server loads configuration from environment variables.
24      2: The server loads configuration from a TOML configuration file.
25      3: Environment variables take precedence over TOML configuration values for the same setting.
26      4: The Cooked base URL defaults to https://cooked.wiki.
27      4-1: COOKED_BASE_URL configures the Cooked base URL.
28      4-2: TOML cooked.base_url configures the Cooked base URL.
29      5: The server validates configured HTTP URLs before serving.
30      6: The server can be pointed at a specific TOML configuration file with --config.
31      7: If no TOML configuration path is supplied, the server loads config.toml from $XDG_CONFIG_HOME/cooked-mcp.
32      7-1: If XDG_CONFIG_HOME is unset, the server loads config.toml from ~/.config/cooked-mcp.
33      8: HTTP transport address is configurable with --http-addr.
34      8-1: COOKED_MCP_HTTP_ADDR configures the HTTP transport address.
35      8-2: TOML mcp.http_addr configures the HTTP transport address.
36
37constraints:
38  SINGLE_USER:
39    requirements:
40      1: The server supports exactly one configured Cooked account per process.
41      2: MCP requests do not provide or select Cooked usernames.
42      3: Multi-account routing, per-client users, and per-request Cooked credentials are out of scope.
43  SECURITY:
44    requirements:
45      1: HTTP transport refuses non-loopback listeners unless MCP HTTP authentication is configured.
46      2: HTTP authentication secrets are never logged.
47      3: HTTP transport supports bearer-token authentication.
48      4: HTTP bearer tokens can be configured through COOKED_MCP_HTTP_TOKEN.
49      5: HTTP bearer tokens can be configured through TOML mcp.http_token.
50      6: HTTP bearer authentication uses the Authorization header with the Bearer scheme.
51      7: When an HTTP token is configured, every MCP HTTP request must provide the matching bearer token.
52      8:
53        requirement: TOML mcp.http_token and mcp.http_token_cmd are mutually exclusive.
54        deprecated: true
55      9: COOKED_MCP_HTTP_TOKEN takes precedence over TOML mcp.http_token.
56      10: TOML mcp.http_token follows the same config value resolution, trimming, timeout, and secrecy rules as Cooked credential settings.
57      11: Empty HTTP bearer tokens are rejected before serving.
58      12: TOML mcp.http_token uses config-values.RESOLUTION.1.
59      13: TOML mcp.http_token may reference any existing environment variable through config value syntax.
60      14: Separate TOML mcp.http_token_cmd is not supported in this version.
61  COMPATIBILITY:
62    requirements:
63      1: The server does not require MCP resource support from clients.
64      2: Every operation described by the cooked-mcp feature specs is available through MCP tools.
65      3: Agents do not need to call Cooked REST endpoints directly.
66  VERIFICATION:
67    requirements:
68      1: Startup and configuration behaviour is verified without contacting the real Cooked service.