# mcp-elicitation-test

A minimal MCP (Model Context Protocol) **stdio server whose sole purpose is to
raise elicitation requests** (`elicitation/create`) from inside tool calls, so
that elicitation plumbing in MCP clients and agent platforms can be exercised
end-to-end.

Built as the test fixture for **APT-798 — "Elicitation Requests from cagent
Background Jobs"** on the Docker Agentic Platform, but it is a plain,
spec-conformant MCP server usable with any client that declares the
`elicitation` capability.

## Tools

| Tool | Elicitation | Purpose |
| --- | --- | --- |
| `ping` | none | Sanity check that the MCP server is wired up at all. |
| `ask_user` | 1 string field | Single-question form elicitation. `question` (required), `delay_seconds` (optional, 0–600) sleeps **before** raising the elicitation — use it to guarantee the elicitation fires *between turns* when called from a detached background job. |
| `ask_user_form` | string + boolean + enum + number | Multi-field form elicitation to exercise form-generation UIs across all primitive field types. `topic` (optional), `delay_seconds` (optional). |

All tools are annotated `readOnlyHint: true` / `destructiveHint: false`. This
matters: hosts that gate tool calls on destructiveness (docker-agent, the
Docker Agentic Platform) auto-approve read-only tools, and **non-interactive
background contexts auto-deny any tool call that would need approval** — so
without these annotations the elicitation would never even be raised from a
background job.

Every elicitation waits up to `ELICIT_TIMEOUT_MS` (default **1 hour**) for the
human response. Each tool returns a JSON report (`action`, `content`,
`waited_ms`, timestamps) so the calling agent's transcript records exactly
what the elicitation round-trip produced.

## Run

```bash
npm install --omit=dev
node server.js          # speaks MCP over stdio
```

Or via the `bin` entry after `npm install -g .`: `mcp-elicitation-test`.

## Smoke test

`smoke-test.mjs` spawns the server, declares the `elicitation` capability,
answers the elicitation programmatically, and prints the round-trip:

```bash
node smoke-test.mjs
```

## Using from a docker-agent (cagent) config

```yaml
agents:
  root:
    # ...
    toolsets:
      - type: mcp
        command: node
        args: ["/home/agent/mcp-elicitation-test/server.js"]
```

See `platform/` for the full test-agent YAML used for APT-798 end-to-end
testing on the Docker Agentic Platform (foreground, `transfer_task`, and
`run_background_agent` trigger paths).

## License

Apache-2.0