pinpointmcp

Pinpoint MCP Server

MCP server for the Pinpoint testing and bug tracking platform. Enables AI agents in Claude Code, Cursor, and other MCP-compatible environments to manage projects, environments, test requests, bug reports, Spectre scan findings, and dependency insights directly from the editor.

Quick Start

Install from npm

npx -y pinpointmcp@latest

That's it. The server starts without any pre-configuration and exposes a configure tool so your AI agent can set up credentials interactively. You can also pre-configure via environment variables or a dotfile (see Configuration below).

Configuration

The server resolves credentials in this order:

• Environment variables (highest precedence)
• Dotfile at ~/.pinpoint/config.json
• Unconfigured (server starts, all tools return setup guidance until configured)

Option 1: Environment Variables

Variable	Required	Default	Description
PINPOINT_TOKEN	No	n/a	API authentication token
PINPOINT_API_URL	No	https://api.testwithpinpoint.com	API base URL

export PINPOINT_TOKEN=your-token-here

Option 2: Interactive Configuration (First-Boot)

Launch the server without any token set. The agent can then call the configure tool:

{ "token": "your-pinpoint-api-token" }

The server validates the token against the API, swaps in a live client, and persists the credentials to ~/.pinpoint/config.json (with 0600 file permissions) for future sessions.

Option 3: Dotfile

Create ~/.pinpoint/config.json manually:

{
  "token": "your-pinpoint-api-token",
  "apiUrl": "https://api.testwithpinpoint.com"
}

Claude Code / Cursor / Windsurf

Add to your project's .mcp.json (or the equivalent for your platform):

{
  "mcpServers": {
    "pinpoint": {
      "command": "npx",
      "args": ["-y", "pinpointmcp"]
    }
  }
}

If you have a token ready, you can pass it as an environment variable to skip the interactive setup:

{
  "mcpServers": {
    "pinpoint": {
      "command": "npx",
      "args": ["-y", "pinpointmcp"],
      "env": {
        "PINPOINT_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "pinpoint": {
      "command": "npx",
      "args": ["-y", "pinpointmcp"]
    }
  }
}

Tech Stack

• Runtime: Node.js >= 18
• Language: TypeScript 5.9+
• MCP SDK: @modelcontextprotocol/sdk 1.27+
• Validation: Zod 4.3+
• Testing: Vitest 4.0+
• Build: TypeScript compiler (tsc)

Project Structure

src/
├── index.ts                 # Main server entry point
├── client.ts                # Pinpoint API client
├── client-holder.ts         # Client lifecycle management
├── config.ts                # Configuration loading
├── config-store.ts          # Persistent config storage
├── setup-message.ts         # Unconfigured-state helpers (used by every tool/resource/prompt)
├── types.ts                 # Shared TypeScript types
├── __tests__/               # Vitest test suite (18 files)
│   ├── analysis-resources.test.ts
│   ├── analysis-tools.test.ts
│   ├── client.test.ts
│   ├── client-holder.test.ts
│   ├── config.test.ts
│   ├── config-store.test.ts
│   ├── configure-tool.test.ts
│   ├── environment-tools.test.ts
│   ├── graph-query-tools.test.ts
│   ├── integration.test.ts
│   ├── project-tools.test.ts
│   ├── prompts.test.ts
│   ├── report-tools.test.ts
│   ├── request-tools.test.ts
│   ├── resources.test.ts
│   ├── setup-message.test.ts
│   ├── tools.test.ts
│   └── update-tools.test.ts
├── tools/                   # MCP tool implementations (25 tools)
│   ├── index.ts             # Barrel export
│   ├── configure.ts         # Runtime configuration
│   ├── list-bugs.ts         # Bug listing
│   ├── get-bug.ts           # Bug details
│   ├── update-bug-status.ts # Bug status updates
│   ├── list-projects.ts     # Project listing
│   ├── create-project.ts    # Project creation
│   ├── update-project.ts    # Project updates
│   ├── delete-project.ts    # Project deletion
│   ├── list-environments.ts # Environment listing
│   ├── add-environment.ts   # Environment creation
│   ├── update-environment.ts# Environment updates
│   ├── remove-environment.ts# Environment deletion
│   ├── list-requests.ts     # Test request listing
│   ├── create-request.ts    # Test request creation
│   ├── get-request.ts       # Test request details
│   ├── get-report.ts        # Report details
│   ├── download-report.ts   # Report download URLs
│   ├── list-dispatch-reports.ts # Reports for a dispatch
│   ├── list-analysis-findings.ts # Spectre scan findings
│   ├── list-analysis-runs.ts    # Spectre scan runs
│   ├── get-analysis-finding.ts  # Scan finding details
│   ├── update-finding-status.ts # Finding status updates
│   └── graph-query.ts       # Blast radius, dependency chain, test coverage
├── resources/               # MCP resource implementations
│   ├── index.ts             # Barrel export
│   ├── bugs.ts              # Bug resources
│   ├── projects.ts          # Project resources
│   ├── requests.ts          # Request resources
│   └── analysis.ts          # Scan and finding resources
└── prompts/                 # MCP prompt templates
    ├── index.ts             # Barrel export
    ├── solve-bug.ts         # Bug solving workflow
    ├── review-request.ts    # Test request review
    └── fix-finding.ts       # Scan finding fix workflow

Build and Run

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run the server (after building)
npm start

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Development mode (watch for changes)
npm run dev

Tools

configure

Configure the server with an API token at runtime. Validates the token before persisting.

Parameter	Type	Required	Default	Description
token	string	Yes	n/a	Your Pinpoint API token
api_url	string	No	https://api.testwithpinpoint.com	API base URL for self-hosted instances

Behavior:

• Validates the token by making a lightweight API call
• On success: swaps the live client, persists to ~/.pinpoint/config.json, returns confirmation
• On validation failure: returns an error without persisting
• On write failure: configures the current session and warns about persistence

Bug Management

list_bugs

List bug reports filtered by status and project.

Parameter	Type	Required	Default	Description
status	string	No	all non-verified	Filter: open, in_progress, in_review, needs_rework, complete, verified. Omit to see all active bugs. Supports comma-separated values (e.g., "open,in_progress,needs_rework")
project	string	No	n/a	Filter by project name
cursor	string	No	n/a	Cursor token from a previous response for efficient pagination through large lists
page	number	No	0	Page number (0-indexed). Ignored when cursor is provided
size	number	No	20	Page size (max 200)

get_bug

Get detailed information about a specific bug report, including description, reproduction steps, expected/actual behavior, and environment.

Parameter	Type	Required	Description
id	string	Yes	Bug report UUID

update_bug_status

Update the status of a bug report.

Parameter	Type	Required	Description
id	string	Yes	Bug report UUID
status	enum	Yes	New status: open, in_progress, complete (only Pinpoint staff can set in_review, needs_rework, or verified)
resolution	string	No	Resolution notes (recommended when marking complete)

Bug Status Lifecycle

Pinpoint uses a multi-gate verification model to ensure bugs are truly fixed before they leave your board. Each bug progresses through six statuses:

OPEN ──► IN_PROGRESS ──► COMPLETE ──► IN_REVIEW ──► VERIFIED
                             │            │
                             │      NEEDS_REWORK
                             │            │
                             └── OPEN ◄───┘

Status	Who sets it	Meaning
open	Pinpoint	Bug discovered during testing. Needs attention.
in_progress	Customer	Your team is actively working on a fix.
complete	Customer	Your team believes the fix is deployed. First quality gate.
in_review	Pinpoint staff only	Pinpoint is actively verifying the fix in your environment.
needs_rework	Pinpoint staff only	Pinpoint found the bug still reproduces. Returned for additional work.
verified	Pinpoint staff only	Pinpoint verified the fix works in your environment. Final quality gate.

Only Pinpoint staff can set in_review, needs_rework, or verified. If staff find the bug still reproduces after you mark it complete, they set needs_rework so your team can investigate further.

Bug Workflow

List all active bugs

Call list_bugs with no status parameter to see every bug that is not verified. This returns all OPEN, IN_PROGRESS, IN_REVIEW, NEEDS_REWORK, and COMPLETE bugs in a single request.

{ "project": "my-app" }

Filter by project

Narrow results to bugs in a specific codebase so you can focus on what you are actively changing.

{ "project": "checkout-service" }

Triage with multi-status filtering

Use comma-separated status values to see only bugs that still need attention. Filtering to "open,in_progress" excludes bugs your team already marked complete.

{ "status": "open,in_progress", "project": "checkout-service" }

Fix a bug end-to-end

• Find open bugs for your project:

  list_bugs { "status": "open", "project": "checkout-service" }
  

• Read the details including reproduction steps and expected behavior:

  get_bug { "id": "bug-uuid-here" }
  

• Claim the bug so your team knows someone is on it:

  update_bug_status { "id": "bug-uuid-here", "status": "in_progress" }
  

• Fix and deploy the code in your editor or through your AI agent.

• Mark complete with a note describing what changed:

  update_bug_status { "id": "bug-uuid-here", "status": "complete", "resolution": "Fixed null check in payment validation; added unit test" }
  

• Pinpoint verifies the fix during the next test cycle and marks the bug as verified if it passes. If the bug still reproduces, Pinpoint reopens it with updated details.

Paginate large bug lists

For projects with many bugs, use cursor-based pagination. The response includes hasMore and nextCursor fields when additional pages exist.

First request:

list_bugs { "project": "large-project", "size": 50 }

If the response contains "hasMore": true and a "nextCursor" value, pass that cursor to fetch the next page:

list_bugs { "project": "large-project", "size": 50, "cursor": "returned-cursor-token" }

Continue until hasMore is false. When a cursor is provided, the page parameter is ignored.

Project Management

list_projects

List all projects for your organization.

Parameter	Type	Required	Default	Description
page	number	No	0	Page number (0-indexed)
size	number	No	20	Page size (max 200)

create_project

Create a new project in your organization.

Parameter	Type	Required	Description
name	string	Yes	Project name
description	string	No	Project description
type	string	No	Project type (UI, API, CLI, MCP)

update_project

Update a project's name, description, or type.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID
name	string	No	New project name
description	string	No	New project description
type	string	No	New project type

delete_project

Delete a project by ID.

Parameter	Type	Required	Description
id	string	Yes	Project UUID

Environment Management

list_environments

List environments for a project.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID

add_environment

Add a new environment to a project.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID
name	string	Yes	Environment name (e.g., staging, production)
baseUrl	string	Yes	Base URL for the environment
isDefault	boolean	No	Whether this is the default environment

update_environment

Update an environment's configuration.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID
environmentId	string	Yes	Environment UUID to update
name	string	No	New environment name
baseUrl	string	No	New base URL
isDefault	boolean	No	Set as the default environment

remove_environment

Remove an environment from a project.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID
environmentId	string	Yes	Environment UUID to remove

Test Request Management

list_requests

List test requests for your account.

Parameter	Type	Required	Default	Description
page	number	No	0	Page number (0-indexed)
size	number	No	20	Page size (max 200)

create_request

Create a new manual test request (dispatch).

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID to dispatch tests for
environment	string	Yes	Target environment name (e.g., staging, production)
buildUrl	string	No	CI/CD build URL
commitSha	string	No	Git commit SHA
branch	string	No	Git branch name
triggeredBy	string	No	Who triggered this request

get_request

Get detailed information about a specific dispatch.

Parameter	Type	Required	Description
id	string	Yes	Dispatch UUID

Report Management

get_report

Get detailed information about a specific report.

Parameter	Type	Required	Description
id	string	Yes	Report UUID

download_report

Get a presigned download URL for a report attachment.

Parameter	Type	Required	Description
id	string	Yes	Report UUID

Note: Presigned URLs expire in 1 hour.

list_dispatch_reports

List all reports for a specific dispatch event.

Parameter	Type	Required	Description
dispatch_id	string	Yes	Dispatch event UUID

Spectre Scan

Spectre is Pinpoint's static analysis engine. These tools let your agent browse scan results and triage findings without leaving the editor.

list_scan_runs

List Spectre scan runs for a project, showing commit, branch, and finding counts.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID

list_scan_findings

List Spectre scan findings for a project, filtered by category, severity, or status.

Parameter	Type	Required	Default	Description
projectId	string	Yes	n/a	Project UUID
category	string	No	n/a	Filter by finding category (e.g., CONTRACT_MISMATCH, DEAD_CODE, MISSING_VALIDATION)
severity	string	No	n/a	Filter by severity: LOW, MEDIUM, HIGH, CRITICAL
status	string	No	n/a	Filter by status: OPEN, ACKNOWLEDGED, RESOLVED, FALSE_POSITIVE
page	number	No	0	Page number (0-indexed)
size	number	No	20	Page size (max 200)

get_scan_finding

Get detailed information about a specific Spectre scan finding, including source location, description, suggested fix, and related components.

Parameter	Type	Required	Description
findingId	string	Yes	Scan finding UUID

update_finding_status

Update the status of a scan finding.

Parameter	Type	Required	Description
findingId	string	Yes	Scan finding UUID
status	enum	Yes	New status: ACKNOWLEDGED, RESOLVED, or FALSE_POSITIVE

Dependency Insights

Query the project dependency graph built by Spectre scans. Useful for understanding change impact and identifying untested components.

get_blast_radius

Compute the blast radius for a component in a project's dependency graph. Returns the proportion of the graph reachable within the specified hop distance, along with the names of affected components.

Parameter	Type	Required	Default	Description
projectId	string	Yes	n/a	Project UUID
vertexName	string	Yes	n/a	Name of the component to compute blast radius from
maxHops	number	No	3	Maximum BFS traversal depth (1 to 10)

get_dependency_chain

Traverse the dependency chain from a component in a project's graph. Returns the chain of dependencies with relationship labels, limited by the specified depth.

Parameter	Type	Required	Default	Description
projectId	string	Yes	n/a	Project UUID
vertexName	string	Yes	n/a	Name of the component to start traversal from
maxDepth	number	No	5	Maximum DFS traversal depth (1 to 20)

get_test_coverage

Calculate test coverage for a scope in a project's graph by examining tested-by edge ratios. Returns the percentage of components that have associated tests.

Parameter	Type	Required	Description
projectId	string	Yes	Project UUID
scope	string	Yes	Scope prefix to filter components (e.g., AuthService, com.example.auth)

Resources

Resources provide read-only access to Pinpoint data via URIs.

URI	Format	Description
pinpoint://bugs	JSON	All non-verified bugs as a JSON array (OPEN, IN_PROGRESS, IN_REVIEW, NEEDS_REWORK, COMPLETE)
pinpoint://bugs/{id}	Markdown	Detailed bug report rendered as Markdown
pinpoint://projects	JSON	All projects as a JSON array
pinpoint://projects/{id}	Markdown	Detailed project information rendered as Markdown
pinpoint://projects/{id}/scans	JSON	Summary of latest scan run and finding counts by severity
pinpoint://requests/{id}	Markdown	Detailed test request information rendered as Markdown
pinpoint://findings/{id}	Markdown	Detailed scan finding with location, description, and related components

Prompts

Prompts provide structured workflows for common tasks.

solve_bug

Structured prompt for analyzing and fixing a specific bug. Assembles the title, description, reproduction steps, expected/actual behavior, and environment into a context block, then asks the agent to identify the root cause, implement a fix, and create a merge request.

Argument	Type	Required	Description
bug_id	string	Yes	UUID of the bug to solve

review_request

Analyze test request results and associated reports. Gathers all reports for a dispatch event and asks the agent to identify patterns across bugs and suggest improvements.

Argument	Type	Required	Description
request_id	string	Yes	UUID of the test request to review

fix_finding

Structured prompt for fixing a specific Spectre scan finding in your codebase. Assembles the finding's location, description, severity, suggested action, related components, and blast radius into a context block, then asks the agent to implement the fix and verify with tests.

Argument	Type	Required	Description
finding_id	string	Yes	UUID of the scan finding to fix

Prerequisites

• Node.js: Version 18 or higher
• Pinpoint Account: Sign up at testwithpinpoint.com
• API Token: Generate from the Pinpoint dashboard (Settings > API Tokens)

Troubleshooting

• Server starts but tools return setup guidance: No token is configured. Either set PINPOINT_TOKEN, create the dotfile, or ask the agent to call the configure tool.
• "Token validation failed": The token was rejected by the API. Verify it is valid and has not expired. Check the Pinpoint dashboard under Settings > API Tokens.
• "Could not save configuration to disk": The server configured successfully for this session but could not write ~/.pinpoint/config.json. Check directory permissions on ~/.pinpoint/.
• "Authentication failed" on tool calls: Your stored or environment token may have expired. Re-run the configure tool with a fresh token.
• Connection errors: Check PINPOINT_API_URL and confirm network connectivity to the API.
• Server not discovered by Claude Code: Ensure .mcp.json exists in the project root and that npm run build has been executed so dist/index.js is present.
• TypeScript compilation errors: Ensure you have TypeScript 5.9+ installed and run npm install to install dependencies.
• Test failures: Run npm test to execute the test suite. Ensure all dependencies are installed and the build is up to date.