io.github.Eason0in/testlink-mcp

testlink-mcp

An AI-friendly, safety-first Model Context Protocol server for TestLink 1.9.20. It exposes normalized discovery and analysis tools, bounded cursor pagination, structured output, and preview-before-apply writes over stdio.

This repository is a clean implementation based on TestLink's public XML-RPC interface and the public MCP SDK. It has no dependency on a private TestLink package or private source tree.

Highlights

• Starts without credentials so MCP clients can discover all tools, resources, and prompts.
• Explicit deterministic demo mode for evaluation and onboarding.
• structuredContent, outputSchema, tool annotations, cursor pagination, and stable error codes.
• Attachment metadata only; attachment content and base64 payloads are removed.
• Writes disabled by default. There is no delete tool.
• Every apply requires confirm: true, an unexpired single-use 10-minute preview, and an unchanged server snapshot.
• Side-effect calls are never automatically retried; apply attempts are written to a redacted operation ledger.
• Runtime guard blocks unsupported/EOL odd Node releases and security patch levels below the declared floor.

Safe write demo

The demo uses synthetic data only. It shows the required safety boundary: Preview a proposed change, inspect the bounded diff, then call apply with the exact preview ID and confirm: true. No write happens during preview. The editable source frames are in docs/assets/testlink-safety.

Requirements

• Node.js ^22.23.2 || ^24.18.1 || ^26.5.1
• TestLink 1.9.20 with its XML-RPC API enabled

The development and container baseline is Node 24.19.0 LTS. CI also runs Node 22.23.2 and 26.7.0.

Quick start

nvm use
npm ci
npm run build
TESTLINK_DEMO_MODE=true node dist/cli.js

Future npm invocation after publication:

npx -y testlink-mcp@1.0.8

MCP client configuration:

{
  "mcpServers": {
    "testlink": {
      "command": "npx",
      "args": ["-y", "testlink-mcp@1.0.8"],
      "env": {
        "TESTLINK_URL": "https://testlink.example.com/testlink",
        "TESTLINK_DEV_KEY": "your-testlink-dev-key"
      }
    }
  }
}

Do not put real credentials in tracked files. Copy .env.example to an ignored .env, or inject environment variables from your MCP client/secret manager.

Tools

All tools return:

{
  "ok": true,
  "data": {},
  "meta": {
    "source": "testlink",
    "requestId": "..."
  }
}

Failures use ok: false with { code, message, retryable, details? }. Consumers should branch on error.code, not message text.

Safe write workflow

1. Search for an existing case and retrieve its current version.
2. Validate the desired test case.
3. Call the relevant preview tool.
4. For a create, provide the TestLink authorLogin; desiredCase.suiteId, summary, and steps are also required by TestLink 1.9.20.
5. Show proposedChanges to the user and obtain explicit confirmation.
6. Call apply with the preview ID and confirm: true within 10 minutes.
7. A confirmed apply consumes its preview before any side effect. After any success, conflict, or failure, create and review a new preview before trying again.
8. If apply returns OUTCOME_UNKNOWN, do not retry. The remote write may have succeeded; reconcile the TestLink case, plan membership, or execution result first.

Enable writes only in the server process that should perform them:

TESTLINK_WRITE_ENABLED=true npx -y testlink-mcp@1.0.8

The default ledger path is ~/.local/state/testlink-mcp/operations.jsonl. Override it with TESTLINK_LEDGER_PATH. Before a remote write, the server persists an attempted row; it then records applied or outcome_unknown. The ledger contains hashes and redacted outcomes, not developer keys.

Configuration

Demo mode is explicit and wins over remote configuration:

TESTLINK_DEMO_MODE=true TESTLINK_WRITE_ENABLED=true node dist/cli.js

Development

npm ci
npm run check
npm test
npm run eval
npm run build
npm audit --omit=dev --audit-level=high
npm pack --dry-run

The offline tool-selection eval checks that common user intents select search, validation, preview, and apply tools distinctly. It is deterministic and does not send data to an external model.

Docker

The image runs as a non-root user and uses Node 24.19.0. Build without pushing:

docker buildx build --platform linux/amd64,linux/arm64 --tag testlink-mcp:local --output type=oci,dest=testlink-mcp.oci.tar .

Future image name after approval and publication: ghcr.io/eason0in/testlink-mcp:1.0.8.

Release policy

Version 1.0.8 is release-ready but publication remains an explicit action. The protected release workflow requires a signed version tag, reruns the complete test/eval/audit/SBOM/package gates, publishes npm with provenance, publishes a multi-architecture GHCR image with SBOM and provenance, creates a GitHub Release, and finally publishes the validated MCP Registry entry.

A separate protected live-smoke workflow verifies the installed package against a real TestLink 1.9.20 instance using read-only calls. Its URL and developer key must be stored as environment secrets and are never written to logs.

The package manifest and server.json share the MCP name io.github.Eason0in/testlink-mcp. Registry validation can be run without publishing:

mcp-publisher validate server.json

The account-side setup and submission data for npm, the MCP Registry, Glama, and MCP.so are tracked in Marketplace submission checklist.

Public references

• TestLink 1.9.20 source and release branch
• Model Context Protocol TypeScript SDK
• Official MCP Registry publisher commands

License

MIT