TestCollab MCP Server

1# TestCollab MCP Server
2 
3MCP (Model Context Protocol) server that exposes TestCollab test management functionality to AI assistants like Claude.
4 
5## Features
6 
7### V1.0 (Current)
8- **Test Case Management**
9  - `list_test_cases` - List test cases with filtering, sorting, and pagination
10  - `get_test_case` - Fetch a single test case with full details (including steps)
11  - `create_test_case` - Create test cases with steps and custom fields
12  - `update_test_case` - Update existing test cases
13 
14### Planned
15- Delete test cases
16- Suite management
17- Test plan management
18- Test execution recording
19 
20## Installation
21 
22```bash
23cd tc-mcp-server
24npm install
25npm run build
26```
27 
28## Configuration
29 
30Create a `.env` file or set environment variables:
31 
32```bash
33# Required: API token from TestCollab user profile
34TC_API_TOKEN=your-api-token-here
35 
36# Optional: API base URL (default: http://localhost:1337)
37TC_API_URL=http://localhost:1337
38 
39# Optional: Default project ID (eliminates need to specify project_id in every request)
40TC_DEFAULT_PROJECT=16
41```
42 
43| Variable | Required | Description |
44|----------|----------|-------------|
45| `TC_API_TOKEN` | Yes | API token from TestCollab user profile |
46| `TC_API_URL` | No | API base URL (default: `http://localhost:1337`) |
47| `TC_DEFAULT_PROJECT` | No | Default project ID - if set, `project_id` becomes optional in tool calls |
48 
49Note: For HTTP transport (recommended for multi-client), send credentials per client via headers
50(`X-TC-API-Token`, `X-TC-API-URL`, `X-TC-Default-Project`). Env vars are a global fallback only.
51 
52## Usage
53 
54### HTTP (recommended for multi-client)
55 
56Start the HTTP server:
57 
58```bash
59npm start
60```
61 
62Configure any MCP client with a URL and headers. Example (Codex):
63 
64```toml
65[mcp_servers.testcollab]
66url = "http://localhost:3100/mcp"
67http_headers = { "X-TC-Default-Project" = "17", X-TC-API-Token = "", X-TC-API-URL = "http://localhost:1337" }
68 
69# (optional) for high security - use env var
70#env_http_headers = { "X-TC-Token" = "TESTCOLLAB_MCP_TOKEN" }
71```
72 
73### Stdio (single-client)
74 
75### With Claude Desktop
76 
77Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
78 
79```json
80{
81  "mcpServers": {
82    "testcollab": {
83      "command": "node",
84      "args": ["/path/to/tc-mcp-server/dist/index.js"],
85      "env": {
86        "TC_API_URL": "http://localhost:1337",
87        "TC_API_TOKEN": "your-api-token",
88        "TC_DEFAULT_PROJECT": "16"
89      }
90    }
91  }
92}
93```
94 
95### With Claude Code
96 
97Add to your Claude Code settings (`.claude/settings.json`):
98 
99```json
100{
101  "mcpServers": {
102    "testcollab": {
103      "command": "node",
104      "args": ["./tc-mcp-server/dist/index.js"],
105      "env": {
106        "TC_API_URL": "http://localhost:1337",
107        "TC_API_TOKEN": "your-api-token",
108        "TC_DEFAULT_PROJECT": "16"
109      }
110    }
111  }
112}
113```
114 
115### Manual Testing
116 
117```bash
118# Start the HTTP server (recommended)
119npm start
120 
121# Start the stdio server (single-client)
122TC_API_TOKEN=your-token npm run start:stdio
123```
124 
125## Available Tools
126 
127### list_test_cases
128 
129List test cases from a project with optional filtering.
130 
131**Parameters:**
132| Name | Type | Required | Description |
133|------|------|----------|-------------|
134| `project_id` | number | No* | Project ID (*required if `TC_DEFAULT_PROJECT` not set) |
135| `suite` | number\|string | No | Filter by suite ID or title |
136| `filter` | object | No | Filter conditions |
137| `sort` | array | No | Sort specification |
138| `limit` | number | No | Max results (1-100, default: 50) |
139| `offset` | number | No | Skip N results (default: 0) |
140 
141**Filter Example:**
142```json
143{
144  "project_id": 1,
145  "filter": {
146    "priority": {
147      "filterType": "number",
148      "type": "greaterThanOrEqual",
149      "filter": 1
150    },
151    "title": {
152      "filterType": "text",
153      "type": "contains",
154      "filter": "login"
155    }
156  },
157  "sort": [{ "colId": "updated_at", "sort": "desc" }],
158  "limit": 25
159}
160```
161 
162**Response:**
163```json
164{
165  "rows": [...],
166  "totalCount": 150,
167  "filteredCount": 25
168}
169```
170 
171### get_test_case
172 
173Fetch a single test case with full details (including steps).
174 
175**Parameters:**
176| Name | Type | Required | Description |
177|------|------|----------|-------------|
178| `id` | number | Yes | Test case ID |
179| `project_id` | number | No* | Project ID (*required if `TC_DEFAULT_PROJECT` not set) |
180| `parse_reusable_steps` | boolean | No | Parse reusable steps into full steps (default: true) |
181 
182**Example:**
183```json
184{
185  "id": 1835,
186  "parse_reusable_steps": true
187}
188```
189 
190**Response:**
191```json
192{
193  "success": true,
194  "testCase": {
195    "id": 1835,
196    "title": "login check",
197    "priority": 1,
198    "steps": [
199      { "step_number": 1, "step": "Navigate to login", "expected_result": "Login page loads" },
200      { "step_number": 2, "step": "Enter credentials", "expected_result": null }
201    ]
202  },
203  "stepsMissingExpectedResults": [2]
204}
205```
206 
207### create_test_case
208 
209Create a new test case with optional custom fields.
210 
211**Parameters:**
212| Name | Type | Required | Description |
213|------|------|----------|-------------|
214| `project_id` | number | No* | Project ID (*required if `TC_DEFAULT_PROJECT` not set) |
215| `title` | string | Yes | Test case title |
216| `suite` | number\|string | No | Suite ID or title to place test case in |
217| `description` | string | No | HTML-formatted description |
218| `priority` | number | No | 0=Low, 1=Normal, 2=High (default: 1) |
219| `steps` | array | No | Test steps array |
220| `tags` | array | No | Array of tag IDs |
221| `requirements` | array | No | Array of requirement IDs |
222| `custom_fields` | array | No | Array of custom field values |
223| `attachments` | array | No | Array of attachment file IDs |
224 
225**Example:**
226```json
227{
228  "title": "Verify login with valid credentials",
229  "suite": 123,
230  "priority": 2,
231  "description": "<p>Test user login</p>",
232  "steps": [
233    { "step": "Navigate to login page", "expected_result": "Page loads" },
234    { "step": "Enter valid credentials", "expected_result": "Fields accept input" },
235    { "step": "Click Login", "expected_result": "User logged in" }
236  ],
237  "custom_fields": [
238    { "id": 5, "name": "env_dropdown", "value": 1, "valueLabel": "staging" }
239  ]
240}
241```
242 
243**Response:**
244```json
245{
246  "success": true,
247  "message": "Test case created successfully",
248  "testCase": {
249    "id": 1234,
250    "title": "Verify login with valid credentials",
251    "project": { "id": 16, "name": "My Project" },
252    "suite": { "id": 123, "title": "Login Suite" },
253    "priority": "2"
254  }
255}
256```
257 
258### update_test_case
259 
260Update an existing test case.
261 
262**Parameters:**
263| Name | Type | Required | Description |
264|------|------|----------|-------------|
265| `id` | number | Yes | Test case ID to update |
266| `project_id` | number | No* | Project ID (*required if `TC_DEFAULT_PROJECT` not set) |
267| `title` | string | No | New title |
268| `suite` | number\|string | No | Move to different suite by ID or title |
269| `description` | string | No | HTML-formatted description |
270| `priority` | number | No | 0=Low, 1=Normal, 2=High |
271| `steps` | array | No | Replace all steps |
272| `tags` | array | No | Replace all tags (array of tag IDs) |
273| `requirements` | array | No | Replace all requirements (array of requirement IDs) |
274| `custom_fields` | array | No | Update custom field values |
275| `attachments` | array | No | Replace attachments (array of file IDs) |
276 
277**Example:**
278```json
279{
280  "id": 1234,
281  "title": "Updated: Verify login with valid credentials",
282  "priority": 2,
283  "steps": [
284    { "step": "Navigate to login page", "expected_result": "Page loads" },
285    { "step": "Enter valid credentials", "expected_result": "Fields accept input" },
286    { "step": "Click Login", "expected_result": "User logged in" },
287    { "step": "Verify dashboard", "expected_result": "Dashboard displayed" }
288  ]
289}
290```
291 
292**Response:**
293```json
294{
295  "success": true,
296  "message": "Test case updated successfully",
297  "testCase": {
298    "id": 1234,
299    "title": "Updated: Verify login with valid credentials",
300    "project": { "id": 16, "name": "My Project" },
301    "suite": { "id": 123, "title": "Login Suite" },
302    "priority": "2"
303  }
304}
305```
306 
307## Development
308 
309```bash
310# Install dependencies
311npm install
312 
313# Run in development mode (with hot reload)
314npm run dev
315 
316# Build
317npm run build
318 
319# Run tests
320npm test
321 
322# Type check
323npm run typecheck
324 
325# Lint
326npm run lint
327```
328 
329## Project Structure
330 
331```
332tc-mcp-server/
333├── src/
334│   ├── index.ts          # Entry point
335│   ├── server.ts         # MCP server setup
336│   ├── config.ts         # Configuration
337│   ├── client/
338│   │   └── api-client.ts # TestCollab API client
339│   ├── tools/
340│   │   ├── index.ts      # Tool registry
341│   │   ├── test-cases/
342│   │   │   ├── index.ts
343│   │   │   └── list.ts   # list_test_cases tool
344│   │   └── suites/
345│   │       └── index.ts
346│   └── types/
347│       └── index.ts      # Type definitions
348├── tests/
349│   ├── unit/
350│   └── integration/
351├── package.json
352├── tsconfig.json
353└── README.md
354```
355 
356## Documentation
357 
358- [Installation Guide](docs/install.md) - Step-by-step setup for Claude Code and Claude Desktop
359- [Use Cases](docs/use_cases.md) - Common scenarios and example prompts for chatbot integration
360 
361## License
362 
363UNLICENSED - Private
364