pinpointmcp 0.1.0

package/README.md

@@ -0,0 +1,270 @@
+# 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.
+
+## Quick Start
+
+### Install from npm
+
+```bash
+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:
+
+1. **Environment variables** (highest precedence)
+2. **Dotfile** at `~/.pinpoint/config.json`
+3. **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 |
+
+```bash
+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:
+
+```json
+{ "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:
+
+```json
+{
+  "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):
+
+```json
+{
+  "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:
+
+```json
+{
+  "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):
+
+```json
+{
+  "mcpServers": {
+    "pinpoint": {
+      "command": "npx",
+      "args": ["-y", "pinpointmcp"]
+    }
+  }
+}
+```
+
+## 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
+
+### 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` |
+| `project` | string | No | n/a | Filter by project name |
+| `page` | number | No | `0` | Page number (0-indexed) |
+| `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`, `resolved`, `closed` |
+| `resolution` | string | No | Resolution notes (recommended when resolving) |
+
+## Resources
+
+| URI | Format | Description |
+|-----|--------|-------------|
+| `pinpoint://bugs` | JSON | All open bugs as a JSON array |
+| `pinpoint://bugs/{id}` | Markdown | Detailed bug report rendered as Markdown |
+
+## Prompts
+
+### 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 |
+
+## Development
+
+```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
+```
+
+### Test Suite
+
+77 tests across 10 files:
+
+| 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 |
+
+**Coverage:** 100% statements, 100% lines, 100% functions, 93% branches.
+
+```bash
+npx vitest run --coverage    # Run with coverage report
+```
+
+## Architecture
+
+```
+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
+```
+
+### First-Boot Flow
+
+When no token is available (no env var, no dotfile), the server starts in an unconfigured state:
+
+```
+┌───────────────┐     ┌──────────────┐     ┌───────────────────┐
+│ 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
+```
+
+## 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.

package/dist/client-holder.d.ts

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

package/dist/client-holder.js

@@ -0,0 +1,18 @@
+export class ClientHolder {
+    client;
+    constructor(client = null) {
+        this.client = client;
+    }
+    isConfigured() {
+        return this.client !== null;
+    }
+    getClient() {
+        if (!this.client) {
+            throw new Error("Pinpoint client is not configured. Call the configure tool first.");
+        }
+        return this.client;
+    }
+    setClient(client) {
+        this.client = client;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+import { BugReport, PaginatedResponse, ListBugsOptions } from "./types.js";
+export declare class PinpointClient {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    listBugs(options?: ListBugsOptions): Promise<PaginatedResponse<BugReport>>;
+    getBug(id: string): Promise<BugReport>;
+    updateBugStatus(id: string, status: string, resolution?: string): Promise<BugReport>;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,63 @@
+import { AuthenticationError, NotFoundError, ServerError, ConnectionError, } from "./types.js";
+export class PinpointClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.token = token;
+    }
+    async listBugs(options) {
+        const params = new URLSearchParams();
+        params.set("status", options?.status ?? "open");
+        if (options?.project)
+            params.set("project", options.project);
+        params.set("page", String(options?.page ?? 0));
+        params.set("size", String(options?.size ?? 20));
+        return this.request(`/api/v1/bugs?${params.toString()}`);
+    }
+    async getBug(id) {
+        return this.request(`/api/v1/bugs/${encodeURIComponent(id)}`);
+    }
+    async updateBugStatus(id, status, resolution) {
+        const body = { status };
+        if (resolution !== undefined) {
+            body.resolution = resolution;
+        }
+        return this.request(`/api/v1/bugs/${encodeURIComponent(id)}/status`, {
+            method: "PATCH",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    async request(path, init) {
+        const url = `${this.baseUrl}${path}`;
+        let response;
+        try {
+            response = await fetch(url, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    Accept: "application/json",
+                    ...init?.headers,
+                },
+            });
+        }
+        catch {
+            throw new ConnectionError(this.baseUrl);
+        }
+        if (!response.ok) {
+            switch (response.status) {
+                case 401:
+                    throw new AuthenticationError();
+                case 404:
+                    throw new NotFoundError();
+                default:
+                    if (response.status >= 500) {
+                        throw new ServerError(`Server error: ${response.status} ${response.statusText}`, response.status);
+                    }
+                    throw new ServerError(`Request failed: ${response.status} ${response.statusText}`, response.status);
+            }
+        }
+        return response.json();
+    }
+}

package/dist/config-store.d.ts

@@ -0,0 +1,7 @@
+export interface StoredConfig {
+    token: string;
+    apiUrl: string;
+}
+export declare function getConfigPath(): string;
+export declare function readStoredConfig(): Promise<StoredConfig | null>;
+export declare function writeStoredConfig(config: StoredConfig): Promise<void>;

package/dist/config-store.js

@@ -0,0 +1,27 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function getConfigPath() {
+    return join(homedir(), ".pinpoint", "config.json");
+}
+export async function readStoredConfig() {
+    try {
+        const raw = await readFile(getConfigPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.token === "string" && typeof parsed.apiUrl === "string") {
+            return { token: parsed.token, apiUrl: parsed.apiUrl };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeStoredConfig(config) {
+    const configPath = getConfigPath();
+    const dir = join(homedir(), ".pinpoint");
+    await mkdir(dir, { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export interface PinpointConfig {
+    token: string | null;
+    apiUrl: string;
+}
+export declare function loadConfig(): Promise<PinpointConfig>;

package/dist/config.js

@@ -0,0 +1,25 @@
+import { readStoredConfig } from "./config-store.js";
+export async function loadConfig() {
+    // Env var takes highest precedence
+    const envToken = process.env.PINPOINT_TOKEN ?? null;
+    const envUrl = process.env.PINPOINT_API_URL;
+    if (envToken) {
+        return {
+            token: envToken,
+            apiUrl: envUrl || "https://api.testwithpinpoint.com",
+        };
+    }
+    // Fall back to dotfile
+    const stored = await readStoredConfig();
+    if (stored) {
+        return {
+            token: stored.token,
+            apiUrl: envUrl || stored.apiUrl,
+        };
+    }
+    // Start unconfigured
+    return {
+        token: null,
+        apiUrl: envUrl || "https://api.testwithpinpoint.com",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { PinpointClient } from "./client.js";
+import { ClientHolder } from "./client-holder.js";
+import { registerConfigureTool, registerListBugsTool, registerGetBugTool, registerUpdateBugStatusTool } from "./tools/index.js";
+import { registerBugListResource, registerBugDetailResource } from "./resources/index.js";
+import { registerSolveBugPrompt } from "./prompts/index.js";
+async function main() {
+    const config = await loadConfig();
+    const holder = new ClientHolder(config.token ? new PinpointClient(config.apiUrl, config.token) : null);
+    const server = new McpServer({
+        name: "pinpoint",
+        version: "0.1.0",
+    });
+    // Register configure tool first (always available)
+    registerConfigureTool(server, holder);
+    // Register bug tools, resources, and prompts
+    registerListBugsTool(server, holder);
+    registerGetBugTool(server, holder);
+    registerUpdateBugStatusTool(server, holder);
+    registerBugListResource(server, holder);
+    registerBugDetailResource(server, holder);
+    registerSolveBugPrompt(server, holder);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (holder.isConfigured()) {
+        console.error("Pinpoint MCP server running on stdio");
+    }
+    else {
+        console.error("Pinpoint MCP server running on stdio (unconfigured, use the configure tool to set your API token)");
+    }
+}
+main().catch(console.error);

package/dist/prompts/index.d.ts

@@ -0,0 +1 @@
+export { registerSolveBugPrompt } from "./solve-bug.js";

package/dist/prompts/index.js

@@ -0,0 +1 @@
+export { registerSolveBugPrompt } from "./solve-bug.js";

package/dist/prompts/solve-bug.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientHolder } from "../client-holder.js";
+export declare function registerSolveBugPrompt(server: McpServer, holder: ClientHolder): void;

package/dist/prompts/solve-bug.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { unconfiguredPromptResult } from "../setup-message.js";
+export function registerSolveBugPrompt(server, holder) {
+    server.prompt("solve_bug", "Structured prompt for analyzing and fixing a specific bug", { bug_id: z.string().describe("UUID of the bug to solve") }, async ({ bug_id }) => {
+        if (!holder.isConfigured())
+            return unconfiguredPromptResult();
+        const bug = await holder.getClient().getBug(bug_id);
+        const text = [
+            `Please help me fix the following bug:\n`,
+            `## ${bug.title}`,
+            `**Severity:** ${bug.severity} | **Component:** ${bug.component || "Unknown"}`,
+            bug.description ? `\n### Description\n${bug.description}` : "",
+            bug.stepsToReproduce ? `\n### Steps to Reproduce\n${bug.stepsToReproduce}` : "",
+            bug.expectedBehavior ? `\n### Expected Behavior\n${bug.expectedBehavior}` : "",
+            bug.actualBehavior ? `\n### Actual Behavior\n${bug.actualBehavior}` : "",
+            bug.environment ? `\n### Environment\n${bug.environment}` : "",
+            `\nPlease analyze the bug, identify the root cause, implement a fix, and create a merge request.`,
+        ].filter(Boolean).join("\n");
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text,
+                    },
+                }],
+        };
+    });
+}

package/dist/resources/bugs.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientHolder } from "../client-holder.js";
+export declare function registerBugListResource(server: McpServer, holder: ClientHolder): void;
+export declare function registerBugDetailResource(server: McpServer, holder: ClientHolder): void;

package/dist/resources/bugs.js

@@ -0,0 +1,43 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { unconfiguredResourceResult } from "../setup-message.js";
+export function registerBugListResource(server, holder) {
+    server.resource("bug-list", "pinpoint://bugs", async (uri) => {
+        if (!holder.isConfigured())
+            return unconfiguredResourceResult(uri.href);
+        const result = await holder.getClient().listBugs({ status: "open" });
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(result.content, null, 2),
+                }],
+        };
+    });
+}
+export function registerBugDetailResource(server, holder) {
+    server.resource("bug-detail", new ResourceTemplate("pinpoint://bugs/{id}", { list: undefined }), async (uri, variables) => {
+        if (!holder.isConfigured())
+            return unconfiguredResourceResult(uri.href);
+        const id = Array.isArray(variables.id) ? variables.id[0] : variables.id;
+        const bug = await holder.getClient().getBug(id);
+        const markdown = [
+            `# ${bug.title}`,
+            `**Severity:** ${bug.severity} | **Status:** ${bug.status} | **Component:** ${bug.component || "N/A"}`,
+            bug.description ? `## Description\n${bug.description}` : "",
+            bug.stepsToReproduce ? `## Steps to Reproduce\n${bug.stepsToReproduce}` : "",
+            bug.expectedBehavior ? `## Expected Behavior\n${bug.expectedBehavior}` : "",
+            bug.actualBehavior ? `## Actual Behavior\n${bug.actualBehavior}` : "",
+            bug.environment ? `## Environment\n${bug.environment}` : "",
+            bug.rootCause ? `## Root Cause\n${bug.rootCause}` : "",
+            bug.resolution ? `## Resolution\n${bug.resolution}` : "",
+            `\n**Reporter:** ${bug.reporterName} | **Created:** ${bug.createdAt}`,
+        ].filter(Boolean).join("\n\n");
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: "text/markdown",
+                    text: markdown,
+                }],
+        };
+    });
+}

package/dist/resources/index.d.ts

@@ -0,0 +1 @@
+export { registerBugListResource, registerBugDetailResource } from "./bugs.js";

package/dist/resources/index.js

@@ -0,0 +1 @@
+export { registerBugListResource, registerBugDetailResource } from "./bugs.js";

package/dist/setup-message.d.ts

@@ -0,0 +1,24 @@
+export declare function getSetupText(): string;
+export declare function unconfiguredToolResult(): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
+export declare function unconfiguredResourceResult(uri: string): {
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+};
+export declare function unconfiguredPromptResult(): {
+    messages: Array<{
+        role: "user";
+        content: {
+            type: "text";
+            text: string;
+        };
+    }>;
+};

package/dist/setup-message.js

@@ -0,0 +1,34 @@
+const SETUP_TEXT = [
+    "Pinpoint MCP server is not yet configured.",
+    "",
+    "To get started, call the `configure` tool with your API token:",
+    "",
+    '  { "token": "your-pinpoint-api-token" }',
+    "",
+    "You can find your token in the Pinpoint dashboard under Settings > API Tokens.",
+    "Optionally pass `api_url` if you use a self-hosted instance.",
+].join("\n");
+export function getSetupText() {
+    return SETUP_TEXT;
+}
+export function unconfiguredToolResult() {
+    return {
+        content: [{ type: "text", text: SETUP_TEXT }],
+        isError: true,
+    };
+}
+export function unconfiguredResourceResult(uri) {
+    return {
+        contents: [{ uri, mimeType: "text/plain", text: SETUP_TEXT }],
+    };
+}
+export function unconfiguredPromptResult() {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: { type: "text", text: SETUP_TEXT },
+            },
+        ],
+    };
+}

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientHolder } from "../client-holder.js";
+export declare function registerConfigureTool(server: McpServer, holder: ClientHolder): void;

package/dist/tools/configure.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { PinpointClient } from "../client.js";
+import { writeStoredConfig } from "../config-store.js";
+const DEFAULT_API_URL = "https://api.testwithpinpoint.com";
+export function registerConfigureTool(server, holder) {
+    server.tool("configure", "Configure the Pinpoint MCP server with your API token", {
+        token: z.string().describe("Your Pinpoint API token"),
+        api_url: z.string().optional().describe("Pinpoint API URL (defaults to production)"),
+    }, async (params) => {
+        const apiUrl = params.api_url || DEFAULT_API_URL;
+        const client = new PinpointClient(apiUrl, params.token);
+        // Validate the token with a lightweight call
+        try {
+            await client.listBugs({ size: 1 });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `Token validation failed: ${message}\n\nPlease check your token and try again.` }],
+                isError: true,
+            };
+        }
+        // Token is valid, swap the client
+        holder.setClient(client);
+        // Persist to dotfile
+        let persisted = true;
+        try {
+            await writeStoredConfig({ token: params.token, apiUrl });
+        }
+        catch {
+            persisted = false;
+        }
+        const lines = [
+            "Pinpoint MCP server configured successfully!",
+            "",
+            `API URL: ${apiUrl}`,
+            `Token: ${params.token.slice(0, 8)}...`,
+        ];
+        if (persisted) {
+            lines.push("", "Configuration saved to ~/.pinpoint/config.json for future sessions.");
+        }
+        else {
+            lines.push("", "Warning: Could not save configuration to disk. The token will only be available for this session.");
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    });
+}

package/dist/tools/get-bug.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientHolder } from "../client-holder.js";
+export declare function registerGetBugTool(server: McpServer, holder: ClientHolder): void;

package/dist/tools/get-bug.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { unconfiguredToolResult } from "../setup-message.js";
+export function registerGetBugTool(server, holder) {
+    server.tool("get_bug", "Get detailed information about a specific bug report", {
+        id: z.string().describe("Bug report UUID"),
+    }, async (params) => {
+        if (!holder.isConfigured())
+            return unconfiguredToolResult();
+        try {
+            const bug = await holder.getClient().getBug(params.id);
+            const sections = [
+                `# ${bug.title}`,
+                `**Severity:** ${bug.severity} | **Status:** ${bug.status} | **Component:** ${bug.component || "N/A"}`,
+                bug.description ? `## Description\n${bug.description}` : null,
+                bug.stepsToReproduce ? `## Steps to Reproduce\n${bug.stepsToReproduce}` : null,
+                bug.expectedBehavior ? `## Expected Behavior\n${bug.expectedBehavior}` : null,
+                bug.actualBehavior ? `## Actual Behavior\n${bug.actualBehavior}` : null,
+                bug.environment ? `## Environment\n${bug.environment}` : null,
+                bug.rootCause ? `## Root Cause\n${bug.rootCause}` : null,
+                bug.resolution ? `## Resolution\n${bug.resolution}` : null,
+                `\n**Reporter:** ${bug.reporterName} | **Created:** ${bug.createdAt}`,
+            ].filter(Boolean).join("\n\n");
+            return { content: [{ type: "text", text: sections }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: `Error fetching bug: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { registerListBugsTool } from "./list-bugs.js";
+export { registerGetBugTool } from "./get-bug.js";
+export { registerUpdateBugStatusTool } from "./update-bug-status.js";
+export { registerConfigureTool } from "./configure.js";

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { registerListBugsTool } from "./list-bugs.js";
+export { registerGetBugTool } from "./get-bug.js";
+export { registerUpdateBugStatusTool } from "./update-bug-status.js";
+export { registerConfigureTool } from "./configure.js";

package/dist/tools/list-bugs.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientHolder } from "../client-holder.js";
+export declare function registerListBugsTool(server: McpServer, holder: ClientHolder): void;

package/dist/tools/list-bugs.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { unconfiguredToolResult } from "../setup-message.js";
+export function registerListBugsTool(server, holder) {
+    server.tool("list_bugs", "List bug reports filtered by status and project", {
+        status: z.string().optional().default("open").describe("Filter by bug status (open, in_progress, resolved, closed)"),
+        project: z.string().optional().describe("Filter by project name"),
+        page: z.number().optional().default(0).describe("Page number (0-indexed)"),
+        size: z.number().optional().default(20).describe("Page size (max 200)"),
+    }, async (params) => {
+        if (!holder.isConfigured())
+            return unconfiguredToolResult();
+        try {
+            const result = await holder.getClient().listBugs(params);
+            const formatted = result.content.map(bug => `[${bug.severity.toUpperCase()}] ${bug.title} (${bug.id})\n  Status: ${bug.status} | Component: ${bug.component || "N/A"}`).join("\n\n");
+            const summary = `Found ${result.totalElements} bugs (page ${result.page + 1} of ${result.totalPages})`;
+            return { content: [{ type: "text", text: `${summary}\n\n${formatted}` }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: `Error listing bugs: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/update-bug-status.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ClientHolder } from "../client-holder.js";
+export declare function registerUpdateBugStatusTool(server: McpServer, holder: ClientHolder): void;

package/dist/tools/update-bug-status.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { unconfiguredToolResult } from "../setup-message.js";
+export function registerUpdateBugStatusTool(server, holder) {
+    server.tool("update_bug_status", "Update the status of a bug report", {
+        id: z.string().describe("Bug report UUID"),
+        status: z.enum(["open", "in_progress", "resolved", "closed"]).describe("New status"),
+        resolution: z.string().optional().describe("Resolution notes (recommended when setting status to resolved)"),
+    }, async (params) => {
+        if (!holder.isConfigured())
+            return unconfiguredToolResult();
+        try {
+            const bug = await holder.getClient().updateBugStatus(params.id, params.status, params.resolution);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Bug "${bug.title}" status updated to ${bug.status}${bug.resolution ? `\nResolution: ${bug.resolution}` : ""}`,
+                    }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: `Error updating bug status: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export interface BugReport {
+    id: string;
+    dispatchEventId: string | null;
+    reporterName: string;
+    title: string;
+    severity: string;
+    status: string;
+    component: string | null;
+    description: string | null;
+    stepsToReproduce: string | null;
+    expectedBehavior: string | null;
+    actualBehavior: string | null;
+    environment: string | null;
+    rootCause: string | null;
+    resolution: string | null;
+    fileName: string | null;
+    fileSize: number | null;
+    downloadUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PaginatedResponse<T> {
+    content: T[];
+    page: number;
+    size: number;
+    totalElements: number;
+    totalPages: number;
+}
+export interface ListBugsOptions {
+    status?: string;
+    project?: string;
+    page?: number;
+    size?: number;
+}
+export interface UpdateBugStatusRequest {
+    status: string;
+    resolution?: string;
+}
+export declare class PinpointError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class AuthenticationError extends PinpointError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends PinpointError {
+    constructor(message?: string);
+}
+export declare class ServerError extends PinpointError {
+    constructor(message?: string, statusCode?: number);
+}
+export declare class ConnectionError extends PinpointError {
+    constructor(url: string);
+}

package/dist/types.js

@@ -0,0 +1,33 @@
+// Error hierarchy
+export class PinpointError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "PinpointError";
+    }
+}
+export class AuthenticationError extends PinpointError {
+    constructor(message = "Authentication failed. Check your API token.") {
+        super(message, 401);
+        this.name = "AuthenticationError";
+    }
+}
+export class NotFoundError extends PinpointError {
+    constructor(message = "Resource not found.") {
+        super(message, 404);
+        this.name = "NotFoundError";
+    }
+}
+export class ServerError extends PinpointError {
+    constructor(message = "Server error", statusCode = 500) {
+        super(message, statusCode);
+        this.name = "ServerError";
+    }
+}
+export class ConnectionError extends PinpointError {
+    constructor(url) {
+        super(`Could not connect to ${url}`);
+        this.name = "ConnectionError";
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pinpointmcp",
+  "version": "0.1.0",
+  "description": "MCP server for Pinpoint bug tracking. Enables AI agents to list, inspect, and resolve bugs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pinpointmcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pinpoint",
+    "bug-tracking",
+    "ai-agent",
+    "claude",
+    "testing"
+  ],
+  "author": "Pinpoint",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/testwithpinpoint/pinpoint",
+    "directory": "code/mcp"
+  },
+  "homepage": "https://testwithpinpoint.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}