test-task-server
# mcp-test-task-server-ts
A small MCP server (stdio transport) for test-task scheduling, written in TypeScript.
> **Portfolio demo, not production.** This is a small public project built to
> demonstrate MCP server development in TypeScript. It does not connect to any
> real test system, and it does not represent production TypeScript experience.
> Tasks live in memory only and are "executed" by a fake worker with
> deterministic, simulated outcomes.
## What it does
Three tools, mirroring a simple test-task scheduling design:
| Tool | Description |
| --- | --- |
| `submit_test_task` | Queue a test task (task name + target + optional params). Returns a task id. |
| `get_task_result` | Poll a task by id for its status and result summary. |
| `list_test_tasks` | List all submitted tasks with their statuses. |
Task lifecycle: `queued` → `running` → `passed` / `failed`, driven by a fake
worker after short simulated delays. Outcomes are deterministic:
- `params.expectedOutcome` (`"passed"` | `"failed"`) forces an outcome — handy for demos;
- otherwise the outcome is derived from a hash of the task name (~80% pass).
## What it demonstrates
- MCP server development in TypeScript with `@modelcontextprotocol/sdk` (stdio transport, zod-validated tool schemas)
- A small, testable design: pure tool handlers over an in-memory store, unit-tested with Vitest
- Strict TypeScript (`strict: true`)
## Run it locally
Requires Node.js 20+.
```bash
npm ci
npm run build
npm start
```
The server speaks MCP over stdio, so it needs an MCP client to talk to.
To try it interactively, the MCP Inspector works (optional):
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
Example tool calls (as an MCP client would send them):
```json
// submit_test_task
{ "name": "smoke-login", "target": "staging-web" }
// submit_test_task — force a failure to see the failed path
{ "name": "checkout-flow", "target": "staging-web", "params": { "expectedOutcome": "failed" } }
// get_task_result
{ "taskId": "task-1" }
// list_test_tasks
{}
```
Run the full verification suite (build, unit tests, and a real MCP SDK client
talking to a separate server process over stdio):
```bash
npm test
```
Run only the subprocess smoke test:
```bash
npm run test:smoke
```
The smoke test initializes an MCP session, discovers all three tools, submits
synthetic passing and failing tasks, polls both to their terminal states, and
checks listing, unknown task IDs, invalid inputs, and recovery after errors.
Requests and polling have time limits, and the subprocess is closed even if an
assertion fails. Unit lifecycle tests use a controlled clock to avoid depending
on short wall-clock timing windows.
On 2026-11-15, `npm ci`, `npm run build`, `npm test` (12 tests), and
`npm run test:smoke` passed locally on Windows with Node.js 24.14.1. This validates
the SDK/stdio integration. Client configuration examples below are reference
snippets; this verification covers the SDK client rather than a Claude host.
## Example client configuration
Config snippet only — connect it to a client yourself. Claude Code (`.mcp.json`):
```json
{
"mcpServers": {
"test-task-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-test-task-server-ts/dist/index.js"]
}
}
}
```
Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"test-task-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-test-task-server-ts/dist/index.js"]
}
}
}
```
Replace `/absolute/path/to/...` with the real path on your machine, then restart
the client. On Windows, forward slashes are valid in the JSON path, for example
`E:/projects/mcp-test-task-server-ts/dist/index.js`. Run `npm run build` before
connecting. These are examples; the test commands do not change client settings.
## Project layout
```
src/
index.ts MCP server wiring (stdio transport, tool registration)
tools.ts Tool handlers (pure functions over the store — unit tested)
store.ts In-memory task store + fake worker
store.test.ts Task lifecycle tests
tools.test.ts Tool handler tests
tests/
mcp.integration.test.ts MCP SDK client + subprocess smoke test
```
## License
MIT — see [LICENSE](LICENSE).
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: submit queues a task, get_task_result retrieves one task's outcome by id, and list_test_tasks enumerates all tasks. There is no meaningful overlap between submission, single-result polling, and listing.
All three tools follow a consistent verb_noun pattern (submit_test_task, get_task_result, list_test_tasks) with snake_case throughout. The naming is predictable and readable.
Three tools is on the thin side but matches the minimal async-task lifecycle the server advertises. Each tool earns its place with no filler.
The core submit/poll/list workflow is covered, which is sufficient for demo-grade test task tracking. However, there is no cancel or delete operation, leaving tasks with no lifecycle termination beyond completion.