Testing

Testing the InfluxDB MCP Server

Two-layer test suite using vitest. Protocol tests run without InfluxDB. Integration tests require a live instance and are gated behind an env var.

Prerequisites

Build before testing — tests spawn the compiled build/index.js, not source:

npm run build

Running Tests

Protocol tests (no InfluxDB needed)

npm test

Runs tests/protocol.test.ts only. Integration tests are skipped automatically. Expected runtime: <1 second.

These tests spawn the real server as a child process using the MCP SDK's StdioClientTransport, perform the initialize handshake, and assert on protocol responses. No InfluxDB connection is made — protocol requests (tools/list, resources/list, prompts/list, ping) are answered entirely from the server's in-memory registrations.

Integration tests (live InfluxDB)

Start InfluxDB 3 Core via the provided Docker Compose file:

npm run test:infra:up

This starts an ephemeral Core container on port 8181 using a static admin token from tests/fixtures/admin-token.json (Docker secrets pattern, --object-store memory — no persistent state).

Run integration tests against it:

source env.test.example && npm run test:integration

Tear down when done:

npm run test:infra:down

For a custom InfluxDB instance (different port, Enterprise, etc.), set the env vars directly instead of sourcing the example file:

INFLUX_TEST_ENABLED=true \
INFLUX_DB_INSTANCE_URL=http://localhost:8281/ \
INFLUX_DB_TOKEN=<your_token> \
INFLUX_DB_PRODUCT_TYPE=enterprise \
npm run test:integration

Tests call health_check, list_databases, and execute_query through the MCP protocol.

Watch mode

npm run test:watch

Reruns on file changes. Useful during development.

What the Tests Cover

Analyzing Failures

EXPECTED_TOOL_COUNT mismatch

The most common failure after code changes. The constant in tests/protocol.test.ts (line 7) must match the actual tool count.

After adding or removing a tool, update the constant and comment in tests/protocol.test.ts (the source of truth). Then update the breakdown below for documentation.

To find the current count, start the server briefly and check stderr:

npm run build && INFLUX_DB_INSTANCE_URL=http://localhost:19999/ \
INFLUX_DB_TOKEN=fake INFLUX_DB_PRODUCT_TYPE=core \
node build/index.js &
sleep 1 && kill $!

Look for: [MCP] Server initialized with N tools, N resources, N prompts

The tool count breakdown by category file:

• help.tools.ts (2) + write.tools.ts (1) + database.tools.ts (4)
• query.tools.ts (3) + token.tools.ts (6) + cloud-token.tools.ts (5)
• health.tools.ts (1) = 22 total
• schema.tools.ts (4 tools, currently disabled — commented out in src/tools/index.ts)

"build/index.js not found"

Run npm run build first. The tests/setup.ts guard fails fast with this message if the build artifact is missing.

Initialize handshake timeout

The server process failed to start. Common causes:

• Build is stale after source changes — rebuild with npm run build
• Missing or invalid env vars — protocol tests use a fake config internally, so this usually means createTestClient was called with bad overrides

Integration test: "HEALTHY" not found

InfluxDB instance is unreachable or unhealthy. Verify:

1. Instance is running: curl http://localhost:8181/ping
2. Token is valid
3. INFLUX_DB_PRODUCT_TYPE matches the actual instance type

Two error paths in the server

When diagnosing tool call failures, note the server has two distinct error paths (defined in src/server/index.ts):

• Unknown tool name → throw new Error(...) → SDK converts to McpError → client sees a rejected promise
• Known tool, handler failure → caught in try/catch → returns { content: [{ type: "text", text: "Error: ..." }], isError: true }

Protocol tests assert the thrown error path. Integration tests assert the content-based error path.

Adding New Tests

New protocol test

Add to tests/protocol.test.ts inside the describe("MCP protocol compliance") block. Protocol tests use the shared testClient from beforeAll. No InfluxDB is contacted — only test MCP protocol-level behavior.

New integration test

Add to tests/integration.test.ts inside the describe.skipIf(!RUN)("live InfluxDB integration") block. Call tools via testClient.client.callTool({ name: "...", arguments: {...} }) and assert on the response content[0].text.

Test helper

The createTestClient(env?) factory in tests/helpers/mcp-client.ts spawns a real server process and returns a connected MCP Client. Override env vars by passing a partial record. Always call close() in afterAll.

Reviewing data-plane and admin changes

When a change adds or modifies a tool that talks to an InfluxDB endpoint (writes, queries, database/token management), verify the actual API contract and exercise it against a real instance. Tool descriptions, CHANGELOG entries, and code comments are not authoritative on their own — confirm them.

Verify the API contract first

Confirm the HTTP method, path, and request/response shape against both the InfluxData docs knowledge source and the influxdata/influxdb source (influxdb3_server/src/http.rs routing, influxdb3_types/src/http.rs structs).

Gotchas that have already bitten this repo:

• Core/Enterprise update_database retention is PUT /api/v3/configure/database with retention_period as a duration string ("60d") — not PATCH, not retention_period_ns.
• Core can update retention since v3.2.0 (static docs wrongly say it's immutable).
• /ping and /health use Token auth even for core/enterprise (v1/v2 compat); the admin client uses Bearer. Both are intentional.

Exercise it against a real instance

Admin endpoints (/api/v3/configure/*) need an admin token; health_check does not, so a passing health_check does not prove the token works. Run a self-contained Core for an admin-path test on a free port:

docker run -d --name mcp-it-core -p 8383:8181 \
  -v "$PWD/tests/fixtures/admin-token.json":/admin-token.json:ro \
  influxdb:3-core influxdb3 serve \
  --node-id local-test --object-store memory \
  --admin-token-file /admin-token.json

INFLUX_TEST_ENABLED=true INFLUX_DB_INSTANCE_URL=http://localhost:8383/ \
INFLUX_DB_TOKEN=apiv3_test INFLUX_DB_PRODUCT_TYPE=core \
npx vitest run tests/integration.test.ts

docker rm -f mcp-it-core

This uses the offline preconfigured admin token in tests/fixtures/admin-token.json (token apiv3_test) — the docker-compose.test.yml pattern, but on a port you choose so it does not collide with other local instances.

Token gotcha

v3 tokens are base64 and can contain +, /, and =. Do not extract one with grep -oE 'apiv3_[A-Za-z0-9_-]+' — it truncates at the first base64 character and yields an invalid token (the server returns 401 "the request was not authenticated").

Additional Resources

Reference Files

• .claude/skills/testing/references/test-architecture.md — Detailed test architecture, design decisions, and how protocol tests work without InfluxDB