pinpointmcp 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Pinpoint MCP Server
 
-MCP server for the [Pinpoint](https://testwithpinpoint.com) bug tracking platform. Enables AI agents in Claude Code, Cursor, and other MCP-compatible environments to list bugs, inspect details, update status, and autonomously resolve reported issues.
+MCP server for the [Pinpoint](https://testwithpinpoint.com) 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, and autonomously resolve reported issues.
 
 ## Quick Start
 
@@ -12,14 +12,6 @@ npx -y pinpointmcp
 
 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](#configuration) below).
 
-### Build from source
-
-```bash
-cd code/mcp
-npm install
-npm run build
-```
-
 ## Configuration
 
 The server resolves credentials in this order:
@@ -106,6 +98,75 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
+## 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
+├── types.ts                 # Shared TypeScript types
+├── tools/                   # MCP tool implementations
+│   ├── 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
+├── resources/               # MCP resource implementations
+│   ├── bugs.ts              # Bug resources
+│   ├── projects.ts          # Project resources
+│   └── requests.ts          # Request resources
+└── prompts/                 # MCP prompt templates
+    ├── solve-bug.ts         # Bug solving workflow
+    └── review-request.ts    # Test request review
+```
+
+## Build and Run
+
+```bash
+# 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
@@ -123,18 +184,21 @@ Configure the server with an API token at runtime. Validates the token before pe
 - On validation failure: returns an error without persisting
 - On write failure: configures the current session and warns about persistence
 
-### list_bugs
+### Bug Management
+
+#### list_bugs
 
 List bug reports filtered by status and project.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `status` | string | No | `"open"` | Filter: `open`, `in_progress`, `resolved`, `closed` |
+| `status` | string | No | all non-closed | Filter: `open`, `in_progress`, `resolved`, `closed`. Omit to see all active bugs. Supports comma-separated values (e.g., `"open,in_progress"`) |
 | `project` | string | No | n/a | Filter by project name |
-| `page` | number | No | `0` | Page number (0-indexed) |
+| `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_bug
 
 Get detailed information about a specific bug report, including description, reproduction steps, expected/actual behavior, and environment.
 
@@ -142,7 +206,7 @@ Get detailed information about a specific bug report, including description, rep
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Bug report UUID |
 
-### update_bug_status
+#### update_bug_status
 
 Update the status of a bug report.
 
@@ -152,114 +216,258 @@ Update the status of a bug report.
 | `status` | enum | Yes | New status: `open`, `in_progress`, `resolved`, `closed` |
 | `resolution` | string | No | Resolution notes (recommended when resolving) |
 
-## Resources
+#### Bug Workflow
 
-| URI | Format | Description |
-|-----|--------|-------------|
-| `pinpoint://bugs` | JSON | All open bugs as a JSON array |
-| `pinpoint://bugs/{id}` | Markdown | Detailed bug report rendered as Markdown |
+These examples show how to combine the bug management tools into a practical workflow for tracking and resolving bugs before they reach production.
 
-## Prompts
+##### See all active bugs
 
-### solve_bug
+Call `list_bugs` with no `status` parameter to retrieve every bug that is not closed. This returns all OPEN, IN_PROGRESS, and RESOLVED bugs in a single request, giving you a complete picture of outstanding work.
 
-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.
+```json
+{ "project": "my-app" }
+```
 
-| Argument | Type | Required | Description |
-|----------|------|----------|-------------|
-| `bug_id` | string | Yes | UUID of the bug to solve |
+##### Filter by project
 
-## Development
+When working on a specific codebase, pass the `project` parameter to narrow results to bugs relevant to that project.
 
-```bash
-npm run dev      # Watch mode (recompiles on save)
-npm run build    # Compile TypeScript to dist/
-npm test         # Run all tests
-npm start        # Start the server on stdio
+```json
+{ "project": "checkout-service" }
 ```
 
-### Test Suite
+This focuses your view so you can address bugs in the code you are actively changing.
 
-77 tests across 10 files:
+##### Triage with multi-status filtering
 
-| File | Tests | Coverage |
-|------|-------|----------|
-| `client.test.ts` | 16 | HTTP client behavior, URL construction, headers, error hierarchy |
-| `client-holder.test.ts` | 7 | Mutable client wrapper: configured/unconfigured states, swap |
-| `config.test.ts` | 6 | Config precedence: env var > dotfile > unconfigured |
-| `config-store.test.ts` | 7 | Dotfile read/write, permissions, invalid JSON handling |
-| `configure-tool.test.ts` | 6 | Token validation, persistence, failure modes, truncation |
-| `setup-message.test.ts` | 5 | Setup guidance text for tools, resources, prompts |
-| `tools.test.ts` | 11 | Tool output formatting, pagination, error wrapping, unconfigured guard |
-| `resources.test.ts` | 8 | Static and templated resources, array variables, unconfigured guard |
-| `prompts.test.ts` | 3 | Prompt assembly, null section omission, unconfigured guard |
-| `integration.test.ts` | 8 | Full MCP handshake via `InMemoryTransport`, schema validation |
+Use comma-separated status values to see only bugs that still need attention. For example, filtering to `"open,in_progress"` excludes resolved bugs so you can focus on what remains.
 
-**Coverage:** 100% statements, 100% lines, 100% functions, 93% branches.
-
-```bash
-npx vitest run --coverage    # Run with coverage report
+```json
+{ "status": "open,in_progress", "project": "checkout-service" }
 ```
 
-## Architecture
+##### Investigate and fix a bug
 
-```
-src/
-  index.ts             Entry point: loads config, creates holder, registers handlers
-  config.ts            Async config loader (env var > dotfile > unconfigured)
-  config-store.ts      ~/.pinpoint/config.json read/write with 0600 permissions
-  client.ts            PinpointClient HTTP client for the Pinpoint API
-  client-holder.ts     Mutable wrapper so the client can be swapped at runtime
-  setup-message.ts     Shared setup guidance for unconfigured state
-  types.ts             TypeScript types and error class hierarchy
-  tools/
-    configure.ts       configure tool (token validation + persistence)
-    list-bugs.ts       list_bugs tool handler
-    get-bug.ts         get_bug tool handler
-    update-bug-status.ts  update_bug_status tool handler
-    index.ts           Barrel export
-  resources/
-    bugs.ts            Static bug list and templated bug detail resources
-    index.ts           Barrel export
-  prompts/
-    solve-bug.ts       solve_bug prompt handler
-    index.ts           Barrel export
-  __tests__/
-    client.test.ts
-    client-holder.test.ts
-    config.test.ts
-    config-store.test.ts
-    configure-tool.test.ts
-    setup-message.test.ts
-    tools.test.ts
-    resources.test.ts
-    prompts.test.ts
-    integration.test.ts
-```
+Once you identify a bug to work on, use the full lifecycle:
+
+1. **List bugs** to find candidates:
+   ```json
+   list_bugs { "status": "open", "project": "checkout-service" }
+   ```
+
+2. **Get details** to understand the issue, including reproduction steps and expected behavior:
+   ```json
+   get_bug { "id": "bug-uuid-here" }
+   ```
+
+3. **Mark as in progress** to signal you are actively working on it:
+   ```json
+   update_bug_status { "id": "bug-uuid-here", "status": "in_progress" }
+   ```
+
+4. **Fix the code** in your editor or through your AI agent.
 
-### First-Boot Flow
+5. **Mark as resolved** with notes describing what changed:
+   ```json
+   update_bug_status { "id": "bug-uuid-here", "status": "resolved", "resolution": "Fixed null check in payment validation; added unit test" }
+   ```
 
-When no token is available (no env var, no dotfile), the server starts in an unconfigured state:
+##### Paginate large bug lists with cursor
 
+For projects with many bugs, use cursor-based pagination to walk through results efficiently. The response includes `hasMore` and `nextCursor` fields when additional pages exist.
+
+First request:
+```json
+list_bugs { "project": "large-project", "size": 50 }
 ```
-┌───────────────┐     ┌──────────────┐     ┌───────────────────┐
-│ loadConfig()  │────>│ ClientHolder │────>│ McpServer starts  │
-│ token = null  │     │ client = null│     │ on stdio transport │
-└───────────────┘     └──────────────┘     └───────────────────┘
-                                                    │
-                           ┌────────────────────────┴──────────────────────┐
-                           │                                               │
-                  Agent calls any tool              Agent calls "configure"
-                  (list_bugs, get_bug, ...)         with { token: "..." }
-                           │                                               │
-                  Returns setup guidance           Validates token via API
-                  with instructions to             Swaps client on holder
-                  call "configure"                 Persists to dotfile
-                                                   Returns confirmation
-                                                            │
-                                              All tools now work normally
+
+If the response contains `"hasMore": true` and a `"nextCursor"` value, pass that cursor to fetch the next page:
+```json
+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, so you do not need to track page numbers manually.
+
+### 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 | No | Target environment (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 |
+
+## Resources
+
+Resources provide read-only access to Pinpoint data via URIs.
+
+| URI | Format | Description |
+|-----|--------|-------------|
+| `pinpoint://bugs` | JSON | All non-closed bugs as a JSON array (OPEN, IN_PROGRESS, RESOLVED) |
+| `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://requests/{id}` | Markdown | Detailed test request information rendered as Markdown |
+
+## 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 |
+
+## Prerequisites
+
+- **Node.js:** Version 18 or higher
+- **Pinpoint Account:** Sign up at [testwithpinpoint.com](https://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.
@@ -268,3 +476,5 @@ When no token is available (no env var, no dotfile), the server starts in an unc
 - **"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.

package/dist/client-holder.d.ts

@@ -1,8 +1,11 @@
 import { PinpointClient } from "./client.js";
 export declare class ClientHolder {
     private client;
-    constructor(client?: PinpointClient | null);
+    private customerId;
+    constructor(client?: PinpointClient | null, customerId?: string | null);
     isConfigured(): boolean;
     getClient(): PinpointClient;
+    getCustomerId(): string;
     setClient(client: PinpointClient): void;
+    setCustomerId(customerId: string): void;
 }

package/dist/client-holder.js

@@ -1,7 +1,9 @@
 export class ClientHolder {
     client;
-    constructor(client = null) {
+    customerId;
+    constructor(client = null, customerId = null) {
         this.client = client;
+        this.customerId = customerId;
     }
     isConfigured() {
         return this.client !== null;
@@ -12,7 +14,16 @@ export class ClientHolder {
         }
         return this.client;
     }
+    getCustomerId() {
+        if (!this.customerId) {
+            throw new Error("Customer ID is not available. Call the configure tool first.");
+        }
+        return this.customerId;
+    }
     setClient(client) {
         this.client = client;
     }
+    setCustomerId(customerId) {
+        this.customerId = customerId;
+    }
 }

package/dist/client.d.ts

@@ -1,10 +1,29 @@
-import { BugReport, PaginatedResponse, ListBugsOptions } from "./types.js";
+import { BugReport, PaginatedResponse, CursorPageResponse, ListBugsOptions, Project, TestRequest, DispatchResponse, Report, MeResponse, CreateProjectRequest, UpdateProjectRequest, ManualDispatchRequest, Environment, CreateEnvironmentRequest, UpdateEnvironmentRequest } from "./types.js";
 export declare class PinpointClient {
     private baseUrl;
     private token;
     constructor(baseUrl: string, token: string);
     listBugs(options?: ListBugsOptions): Promise<PaginatedResponse<BugReport>>;
+    listBugsWithCursor(options?: ListBugsOptions): Promise<CursorPageResponse<BugReport>>;
     getBug(id: string): Promise<BugReport>;
     updateBugStatus(id: string, status: string, resolution?: string): Promise<BugReport>;
+    listProjects(customerId: string, page?: number, size?: number): Promise<PaginatedResponse<Project>>;
+    createProject(customerId: string, request: CreateProjectRequest): Promise<Project>;
+    deleteProject(customerId: string, projectId: string): Promise<void>;
+    listRequests(customerId: string, page?: number, size?: number): Promise<PaginatedResponse<TestRequest>>;
+    createRequest(customerId: string, request: ManualDispatchRequest): Promise<TestRequest>;
+    getDispatch(dispatchId: string): Promise<DispatchResponse>;
+    getReport(reportId: string): Promise<Report>;
+    getReportDownloadUrl(reportId: string): Promise<{
+        url: string;
+    }>;
+    getReportsForDispatch(dispatchId: string): Promise<Report[]>;
+    getMe(): Promise<MeResponse>;
+    updateProject(customerId: string, projectId: string, request: UpdateProjectRequest): Promise<Project>;
+    listEnvironments(customerId: string, projectId: string): Promise<Environment[]>;
+    createEnvironment(customerId: string, projectId: string, request: CreateEnvironmentRequest): Promise<Environment>;
+    updateEnvironment(customerId: string, projectId: string, environmentId: string, request: UpdateEnvironmentRequest): Promise<Environment>;
+    deleteEnvironment(customerId: string, projectId: string, environmentId: string): Promise<void>;
+    private handleErrorResponse;
     private request;
 }