# testlink-mcp-server

MCP (Model Context Protocol) server exposing the TestLink XML-RPC API as typed tools for LLM agents (Claude Desktop, Claude Code, etc.).

## Stack

| Concern | Choice |
|---|---|
| Runtime | Node.js ≥ 18, TypeScript, ESM |
| MCP transport | `@modelcontextprotocol/sdk` over stdio |
| TestLink transport | `xmlrpc` client, `devKey` injected on every call |
| Schema validation | `zod` (per-tool input schemas) |
| Tests | `vitest`, XML-RPC client fully mocked |

## Project structure

```
testlink-mcp-server/
├── src/
│   ├── index.ts            # MCP server entry point (registers all tool groups, stdio transport)
│   ├── client.ts            # TestLinkClient: XML-RPC wrapper, retry/timeout, error normalization
│   ├── types.ts              # TestLinkClientConfig, TestLinkError
│   ├── mcp-helpers.ts         # toToolResult(): uniform success/error → MCP content mapping
│   ├── xmlrpc.d.ts            # minimal ambient types for the untyped `xmlrpc` package
│   └── tools/
│       ├── projects.ts        # list_projects, create_project
│       ├── testsuites.ts       # list/create/update/delete_test_suite
│       ├── testcases.ts         # read/create/update/delete_test_case, list_test_cases_in_suite
│       ├── customfields.ts       # get/update_custom_field_value, list_custom_fields_for_project
│       ├── requirements.ts        # list/create/get_requirement, create_requirement_specification, assign_requirements
│       ├── testplans.ts            # list/create/delete_test_plan, add_test_case_to_test_plan, get_test_cases_for_test_plan
│       ├── builds.ts                # create/list/close_build
│       ├── executions.ts             # create/read_test_execution
│       └── diagnostics.ts             # list_available_api_methods (system.listMethods introspection)
├── test/client.test.ts
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── .env.example
```

## Installation

```bash
npm install
npm run build
```

## Configuration

Copy `.env.example` to `.env` and fill in your instance's details:

```bash
cp .env.example .env
```

| Variable | Required | Description |
|---|---|---|
| `TESTLINK_URL` | yes | Full XML-RPC endpoint, e.g. `http://host/testlink/lib/api/xmlrpc/v1/xmlrpc.php` |
| `TESTLINK_API_KEY` | yes | Personal API key from TestLink → *My Settings* → API interface |
| `TESTLINK_TIMEOUT_MS` | no | Per-call network timeout (default `15000`) |
| `TESTLINK_RETRIES` | no | Retry attempts on transient network errors only (default `2`) |
| `TESTLINK_RETRY_DELAY_MS` | no | Base backoff delay, doubled per attempt (default `500`) |

`TESTLINK_API_KEY` is a credential — keep it out of source control (`.env` is already git-ignored) and out of shared MCP configs where other users could read it.

## Running standalone

```bash
npm run dev     # ts-node style, via tsx
# or
npm run build && npm start
```

The server speaks MCP over stdio — it has no meaningful output when run directly in a terminal; it's meant to be launched by an MCP host.

## Claude Desktop configuration

Add a block like this to `claude_desktop_config.json` (Windows: `%APPDATA%\Claude\claude_desktop_config.json`; macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "testlink": {
      "command": "node",
      "args": ["C:/data/mcp-server/testlink/dist/index.js"],
      "env": {
        "TESTLINK_URL": "http://your-testlink-host/testlink/lib/api/xmlrpc/v1/xmlrpc.php",
        "TESTLINK_API_KEY": "your-devkey-here"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config. Run `npm run build` first — the config points at the compiled `dist/index.js`, not the TypeScript source.

## Tools exposed

| Tool | TestLink API method |
|---|---|
| `list_projects` | `tl.getProjects` |
| `create_project` | `tl.createTestProject` |
| `list_test_suites` | `tl.getFirstLevelTestSuitesForTestProject` / `tl.getTestSuitesForTestSuite` |
| `create_test_suite` | `tl.createTestSuite` |
| `update_test_suite` | `tl.updateTestSuite` ⚠️ |
| `delete_test_suite` | `tl.deleteTestSuite` ⚠️ |
| `read_test_case` | `tl.getTestCase` |
| `create_test_case` | `tl.createTestCase` |
| `update_test_case` | `tl.updateTestCase` |
| `delete_test_case` | `tl.deleteTestCase` ⚠️ |
| `list_test_cases_in_suite` | `tl.getTestCasesForTestSuite` |
| `get_custom_field_value` | `tl.getTestCaseCustomFieldDesignValue` |
| `update_custom_field_value` | `tl.updateTestCase` (`customfields` param) |
| `list_custom_fields_for_project` | best-effort probe, see caveat below ⚠️ |
| `list_requirements` | `tl.getRequirements` |
| `create_requirement_specification` | `tl.createRequirementSpecification` |
| `create_requirement` | `tl.createRequirement` |
| `assign_requirements` | `tl.assignRequirements` |
| `get_requirement` | client-side filter over `tl.getRequirements` ⚠️ |
| `list_test_plans` | `tl.getProjectTestPlans` |
| `create_test_plan` | `tl.createTestPlan` |
| `add_test_case_to_test_plan` | `tl.addTestCaseToTestPlan` |
| `get_test_cases_for_test_plan` | `tl.getTestCasesForTestPlan` |
| `delete_test_plan` | `tl.deleteTestPlan` ⚠️ |
| `create_build` | `tl.createBuild` |
| `list_builds` | `tl.getBuildsForTestPlan` |
| `close_build` | `tl.closeBuild` ⚠️ |
| `create_test_execution` | `tl.reportTCResult` |
| `read_test_execution` | `tl.getLastExecutionResult` |
| `list_available_api_methods` | `system.listMethods` (introspection) |

## Known API limitations (⚠️ above)

TestLink's official XML-RPC surface is oriented around CI reporting (create projects/suites/cases/plans/builds, report results) and historically has **no stock endpoints for update/delete on test suites, test cases, or test plans, nor for closing a build or listing custom field definitions**. This server implements those tools anyway, calling the conventionally-named method (`tl.updateTestSuite`, `tl.deleteTestSuite`, `tl.deleteTestCase`, `tl.deleteTestPlan`, `tl.closeBuild`), because some installations add them via patches or newer releases.

**Before relying on any ⚠️-marked tool**, call `list_available_api_methods` (wraps the standard XML-RPC `system.listMethods` introspection call) to confirm your TestLink server actually exposes it. If it doesn't, the call fails as a clear XML-RPC "unknown method" fault surfaced through this server's normal error path — not a silent no-op.

- `get_requirement`: TestLink has no single-requirement lookup; this fetches the full project requirement list via `tl.getRequirements` and filters client-side by requirement id or doc id. Fine for small/medium requirement sets; not paginated.
- `list_custom_fields_for_project`: TestLink's API can only read a *named* custom field's value on a *specific test case* — it cannot enumerate a project's custom field definitions. This tool takes a representative test case plus a list of candidate field names (visible in TestLink Admin → Custom Fields) and probes each one, returning only the fields that resolved to a non-empty value. It cannot discover field names you don't already supply.

## Error handling

TestLink signals failures two ways, both normalized into a single `TestLinkError`:

1. **XML-RPC faults** — transport-level errors (bad method, malformed params).
2. **In-band error payloads** — TestLink often returns HTTP 200 with a body like `[{code: 200, message: "..."}]`, or `{status: false, message: "..."}` for write operations. `TestLinkClient` inspects every response and throws `TestLinkError` for both cases, so callers never have to special-case a "successful" HTTP response that's actually a failure.

Every tool handler wraps its call in `toToolResult()`, so failures come back as an MCP tool result with `isError: true` and a JSON body `{error: true, method, code, message}` — never an uncaught exception that kills the server process.

Network-level errors (`ECONNRESET`, `ETIMEDOUT`, `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`, `EPIPE`) are retried with exponential backoff up to `TESTLINK_RETRIES` times; logical TestLink API errors are never retried, since retrying a duplicate-name or bad-devKey error just repeats the same failure.

## Tests

```bash
npm test
```

`test/client.test.ts` mocks the `xmlrpc` module entirely and covers: devKey injection, both TestLink in-band error shapes, the retry path on transient network errors, no-retry on logical errors, `system.*` calls skipping devKey, and the client-side requirement lookup's not-found path.

## Security notes

- `TESTLINK_API_KEY` grants full API access under whichever TestLink user issued it — treat it like any other credential.
- If `TESTLINK_URL` is `https://`, the client uses `xmlrpc.createSecureClient`; prefer HTTPS whenever your TestLink instance supports it, since the XML-RPC API otherwise sends the devKey in plaintext.
- All tool inputs are validated against explicit `zod` schemas before reaching the TestLink client — malformed input is rejected by the MCP layer rather than forwarded to the XML-RPC endpoint.