koalr-mcp 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# koalr-mcp
+
+Koalr MCP server — connect your engineering metrics to AI agents like Claude Code, Cursor, and others.
+
+## Quick Start
+
+### Generate an API Key
+
+1. Go to [app.koalr.com/settings/api-keys](https://app.koalr.com/settings/api-keys)
+2. Create a new API key with the scopes you need
+3. Copy the key (shown once) — it starts with `koalr_`
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "koalr": {
+      "command": "npx",
+      "args": ["-y", "koalr-mcp"],
+      "env": {
+        "KOALR_API_KEY": "koalr_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "koalr": {
+      "command": "npx",
+      "args": ["-y", "koalr-mcp"],
+      "env": {
+        "KOALR_API_KEY": "koalr_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+# Add to your project's MCP config
+claude mcp add koalr \
+  -e KOALR_API_KEY=koalr_your_key_here \
+  -- npx -y koalr-mcp
+```
+
+## Environment Variables
+
+| Variable        | Description                                          | Default                 |
+| --------------- | ---------------------------------------------------- | ----------------------- |
+| `KOALR_API_KEY` | Your Koalr API key (required). Starts with `koalr_`. | —                       |
+| `KOALR_API_URL` | Koalr API base URL (for self-hosted or local dev)    | `http://localhost:3001` |
+| `MCP_TRANSPORT` | Transport mode: `stdio` (default) or `http`          | `stdio`                 |
+| `PORT`          | Port for HTTP transport mode                         | `3010`                  |
+
+## Available Tools
+
+### Organization
+
+| Tool                     | Description                                                       |
+| ------------------------ | ----------------------------------------------------------------- |
+| `get_org_health`         | Comprehensive org health: DORA tier, cycle time, teams, incidents |
+| `get_well_being_summary` | Developer well-being: focus time, meeting load, burnout signals   |
+
+### DORA Metrics
+
+| Tool               | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `get_dora_summary` | Deploy frequency, lead time, change failure rate, MTTR |
+| `get_dora_trend`   | Weekly trend for any DORA metric                       |
+
+### Pull Requests
+
+| Tool              | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| `get_pr_summary`  | Cycle time, throughput, review health metrics   |
+| `get_open_prs`    | Currently open PRs with age and risk indicators |
+| `get_at_risk_prs` | PRs at risk of being long-running or blocked    |
+
+### Teams
+
+| Tool                | Description                          |
+| ------------------- | ------------------------------------ |
+| `list_teams`        | All teams with IDs and member counts |
+| `get_team`          | Team-level DORA and flow metrics     |
+| `list_team_members` | Team roster with GitHub logins       |
+
+### Repositories
+
+| Tool                | Description                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| `list_repositories` | All repos with health scores                                 |
+| `get_repository`    | Repo metrics: deployment frequency, cycle time, contributors |
+
+### Developers
+
+| Tool                    | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `get_developer`         | Individual developer metrics and recent activity |
+| `list_top_contributors` | Most active contributors by commits and PRs      |
+
+### Search
+
+| Tool     | Description                                      |
+| -------- | ------------------------------------------------ |
+| `search` | Search developers, repos, PRs, and teams by name |
+
+### Coverage
+
+| Tool                   | Description                            |
+| ---------------------- | -------------------------------------- |
+| `get_coverage_summary` | Test coverage by repository with trend |
+
+### Incidents
+
+| Tool                    | Description                                        |
+| ----------------------- | -------------------------------------------------- |
+| `list_recent_incidents` | Recent incidents from PagerDuty/OpsGenie with MTTR |
+
+### AI Adoption
+
+| Tool                      | Description                             |
+| ------------------------- | --------------------------------------- |
+| `get_ai_adoption_summary` | GitHub Copilot and Cursor usage metrics |
+| `get_ai_adoption_trend`   | AI tool adoption trend over time        |
+
+## Example Prompts
+
+Once connected, you can ask your AI agent things like:
+
+- "What is our team's DORA performance tier this month?"
+- "Show me all PRs that have been open for more than 3 days"
+- "Which developers have the highest PR throughput on the backend team?"
+- "How is our AI coding tool adoption trending?"
+- "What was our MTTR for incidents last quarter?"
+- "Find the auth-service repository and show me its deployment frequency"
+
+## HTTP Transport (Remote Hosting)
+
+For hosting the MCP server remotely (e.g., at `mcp.koalr.com`):
+
+```bash
+MCP_TRANSPORT=http PORT=3010 KOALR_API_KEY=koalr_... node dist/index.js
+```
+
+The server exposes `POST /mcp` and `GET /mcp` endpoints following the MCP Streamable HTTP transport spec.
+
+## Local Development
+
+```bash
+# From repo root
+pnpm install
+pnpm exec turbo build --filter=koalr-mcp
+
+# Run in stdio mode (test with MCP Inspector)
+KOALR_API_KEY=koalr_... node apps/mcp/dist/index.js
+
+# Run in HTTP mode
+MCP_TRANSPORT=http KOALR_API_KEY=koalr_... node apps/mcp/dist/index.js
+```

package/dist/client.js

@@ -0,0 +1,42 @@
+const API_URL = process.env['KOALR_API_URL'] ?? 'https://api.koalr.com';
+const API_KEY = process.env['KOALR_API_KEY'] ?? '';
+export async function apiGet(path, params) {
+    const url = new URL(`${API_URL}${path}`);
+    if (params) {
+        Object.entries(params).forEach(([k, v]) => {
+            if (v !== undefined && v !== null && v !== '') {
+                url.searchParams.set(k, v);
+            }
+        });
+    }
+    const res = await fetch(url.toString(), {
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json',
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Koalr API ${res.status} at ${path}: ${body}`);
+    }
+    return res.json();
+}
+export async function apiPost(path, body) {
+    const url = new URL(`${API_URL}${path}`);
+    const res = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Koalr API ${res.status} at ${path}: ${text}`);
+    }
+    return res.json();
+}
+export function formatResult(data) {
+    return JSON.stringify(data, null, 2);
+}

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer } from './server.js';
+import { createServer as createHttpServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+const mode = process.env['MCP_TRANSPORT'] ?? 'stdio';
+async function startStdio() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('Koalr MCP server running on stdio\n');
+}
+async function startHttp() {
+    const port = parseInt(process.env['PORT'] ?? '3010', 10);
+    // Map of sessionId -> transport for stateful connections
+    const transports = new Map();
+    const httpServer = createHttpServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+        // Health check
+        if (req.method === 'GET' && url.pathname === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', server: 'koalr-mcp' }));
+            return;
+        }
+        // MCP endpoint
+        if (url.pathname === '/mcp') {
+            if (req.method === 'POST') {
+                // Check for existing session or create new one
+                const sessionId = req.headers['mcp-session-id'] ?? undefined;
+                let transport;
+                if (sessionId && transports.has(sessionId)) {
+                    transport = transports.get(sessionId);
+                }
+                else if (!sessionId) {
+                    // New session
+                    const newSessionId = randomUUID();
+                    transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => newSessionId,
+                    });
+                    transports.set(newSessionId, transport);
+                    transport.onclose = () => {
+                        transports.delete(newSessionId);
+                    };
+                    const mcpServer = createServer();
+                    await mcpServer.connect(transport);
+                }
+                if (!transport) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid or missing session ID' }));
+                    return;
+                }
+                await transport.handleRequest(req, res);
+                return;
+            }
+            if (req.method === 'GET' || req.method === 'DELETE') {
+                const sessionId = req.headers['mcp-session-id'] ?? undefined;
+                const transport = sessionId ? transports.get(sessionId) : undefined;
+                if (!transport) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Session not found' }));
+                    return;
+                }
+                await transport.handleRequest(req, res);
+                return;
+            }
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    });
+    httpServer.listen(port, () => {
+        process.stderr.write(`Koalr MCP server running on http://localhost:${port}/mcp\n`);
+    });
+}
+if (mode === 'http') {
+    startHttp().catch((err) => {
+        process.stderr.write(`Fatal: ${String(err)}\n`);
+        process.exit(1);
+    });
+}
+else {
+    startStdio().catch((err) => {
+        process.stderr.write(`Fatal: ${String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerDoraTools } from './tools/dora.js';
+import { registerPullRequestTools } from './tools/pull-requests.js';
+import { registerTeamTools } from './tools/teams.js';
+import { registerRepositoryTools } from './tools/repositories.js';
+import { registerDeveloperTools } from './tools/developers.js';
+import { registerSearchTools } from './tools/search.js';
+import { registerCoverageTools } from './tools/coverage.js';
+import { registerIncidentTools } from './tools/incidents.js';
+import { registerAiAdoptionTools } from './tools/ai-adoption.js';
+import { registerOrganizationTools } from './tools/organization.js';
+import { registerDeployRiskTools } from './tools/deploy-risk.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'koalr',
+        version: '0.1.0',
+    });
+    // Register all tool groups
+    registerDoraTools(server);
+    registerPullRequestTools(server);
+    registerTeamTools(server);
+    registerRepositoryTools(server);
+    registerDeveloperTools(server);
+    registerSearchTools(server);
+    registerCoverageTools(server);
+    registerIncidentTools(server);
+    registerAiAdoptionTools(server);
+    registerOrganizationTools(server);
+    registerDeployRiskTools(server);
+    return server;
+}

package/dist/tools/ai-adoption.js

@@ -0,0 +1,20 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerAiAdoptionTools(server) {
+    server.tool('get_ai_adoption_summary', 'Get AI coding tool adoption metrics including GitHub Copilot acceptance rate, Cursor active users, AI-generated code percentage, and suggestions per developer. Use this to understand how the team is using AI coding assistants.', {}, async () => {
+        const data = await apiGet('/api/v1/copilot');
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('get_ai_adoption_trend', 'Get the trend of AI tool adoption over time showing weekly active users, acceptance rates, and code attribution percentages. Use this to track whether AI tool adoption is growing or declining.', {
+        days: z
+            .number()
+            .optional()
+            .describe('Number of days to look back for trend data (default: 90)'),
+    }, async ({ days }) => {
+        const params = {};
+        if (days)
+            params['days'] = String(days);
+        const data = await apiGet('/ai-analytics/trend', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/coverage.js

@@ -0,0 +1,16 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerCoverageTools(server) {
+    server.tool('get_coverage_summary', 'Get test coverage summary per repository showing overall coverage percentage, lines covered, and coverage trend. Use this to understand testing health and identify repositories with low coverage.', {
+        repositoryId: z
+            .string()
+            .optional()
+            .describe('Filter to a specific repository by ID. Omit to see all repositories.'),
+    }, async ({ repositoryId }) => {
+        const params = {};
+        if (repositoryId)
+            params['repositoryId'] = repositoryId;
+        const data = await apiGet('/coverage', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/deploy-risk.js

@@ -0,0 +1,44 @@
+import { z } from 'zod/v3';
+import { apiPost, formatResult } from '../client.js';
+export function registerDeployRiskTools(server) {
+    server.tool('score_pr_for_deploy_risk', "Score a specific pull request for deployment risk using Koalr's 36-signal model. Returns a 0-100 risk score with a detailed factor breakdown covering change entropy, DDL migration detection, author file expertise, PR size, CODEOWNERS violations, and more. Use this to answer \"How risky is this PR?\" or \"Should we merge this before the release?\".", {
+        owner: z.string().describe('GitHub repository owner (org or user). Example: "acme".'),
+        repo: z.string().describe('Repository name. Example: "api-service".'),
+        prNumber: z.number().describe('Pull request number.'),
+        sha: z.string().describe('Head commit SHA.'),
+        title: z.string().describe('PR title.'),
+        body: z.string().optional().describe('PR description body (used to detect risky phrases).'),
+        authorLogin: z.string().optional().describe('GitHub login of the PR author.'),
+        additions: z.number().describe('Lines added.'),
+        deletions: z.number().describe('Lines deleted.'),
+        changedFiles: z.number().describe('Number of files changed.'),
+        files: z
+            .array(z.string())
+            .optional()
+            .describe('List of changed file paths. Used for DDL detection, CODEOWNERS analysis, and entropy calculation. More accurate results when provided.'),
+        hasReview: z
+            .boolean()
+            .optional()
+            .describe('Whether the PR has at least one review (any type).'),
+        hasApproval: z
+            .boolean()
+            .optional()
+            .describe('Whether the PR has at least one approving review.'),
+    }, async ({ owner, repo, prNumber, sha, title, body, authorLogin, additions, deletions, changedFiles, files, hasReview, hasApproval, }) => {
+        const data = await apiPost('/api/v1/pr-risk/score', {
+            repo: `${owner}/${repo}`,
+            prNumber,
+            sha,
+            title,
+            body: body ?? null,
+            authorLogin,
+            additions,
+            deletions,
+            changedFiles,
+            files: files ?? [],
+            hasReview: hasReview ?? false,
+            hasApproval: hasApproval ?? false,
+        });
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/developers.js

@@ -0,0 +1,25 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerDeveloperTools(server) {
+    server.tool('get_developer', "Get metrics for an individual developer including their PR throughput, review activity, average cycle time, and code contributions. Use this when asked about a specific engineer's activity or productivity.", {
+        login: z.string().describe('GitHub username / login of the developer (e.g. "jsmith")'),
+    }, async ({ login }) => {
+        const data = await apiGet('/developer-profiles', { login });
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('list_top_contributors', 'List the most active contributors ranked by commits and PRs merged over a time window. Use this to identify key contributors, bus-factor risks, or to recognize top performers.', {
+        days: z.number().optional().describe('Time window in days to measure activity (default: 30)'),
+        limit: z
+            .number()
+            .optional()
+            .describe('Number of contributors to return (default: 10, max: 50)'),
+    }, async ({ days, limit }) => {
+        const params = {};
+        if (days)
+            params['days'] = String(days);
+        if (limit)
+            params['limit'] = String(limit);
+        const data = await apiGet('/developer-profiles/top-contributors', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/dora.js

@@ -0,0 +1,43 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerDoraTools(server) {
+    server.tool('get_dora_summary', 'Get DORA metrics (deploy frequency, lead time for changes, change failure rate, MTTR) for the organization or a specific team. Use this to understand overall engineering delivery performance and reliability.', {
+        teamId: z.string().optional().describe('Team ID to filter metrics for a specific team'),
+        from: z
+            .string()
+            .optional()
+            .describe('Start date as ISO string (e.g. 2024-01-01). Defaults to 30 days ago.'),
+        to: z
+            .string()
+            .optional()
+            .describe('End date as ISO string (e.g. 2024-01-31). Defaults to today.'),
+    }, async ({ teamId, from, to }) => {
+        const params = {};
+        if (teamId)
+            params['teamId'] = teamId;
+        if (from)
+            params['from'] = from;
+        if (to)
+            params['to'] = to;
+        const data = await apiGet('/api/v1/metrics/dora', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('get_dora_trend', 'Get DORA metric trend over time to see how deployment frequency, lead time, change failure rate, or MTTR has changed week over week. Useful for spotting regressions or improvements.', {
+        metric: z
+            .enum(['deploy_frequency', 'lead_time', 'change_failure_rate', 'mttr'])
+            .describe('Which DORA metric to trend: deploy_frequency, lead_time, change_failure_rate, or mttr'),
+        days: z
+            .number()
+            .optional()
+            .describe('Number of days to look back (default: 90). Max recommended: 365.'),
+        teamId: z.string().optional().describe('Team ID to filter metrics for a specific team'),
+    }, async ({ metric, days, teamId }) => {
+        const params = { metric };
+        if (days)
+            params['days'] = String(days);
+        if (teamId)
+            params['teamId'] = teamId;
+        const data = await apiGet('/api/v1/metrics/dora/trend', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/incidents.js

@@ -0,0 +1,21 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerIncidentTools(server) {
+    server.tool('list_recent_incidents', 'List recent production incidents from PagerDuty or OpsGenie with their severity, MTTR (mean time to recovery), and affected services. Use this to understand reliability posture or investigate a recent outage.', {
+        days: z
+            .number()
+            .optional()
+            .describe('Number of days to look back for incidents (default: 30)'),
+        limit: z.number().optional().describe('Maximum number of incidents to return (default: 20)'),
+    }, async ({ days, limit }) => {
+        const params = {};
+        if (days) {
+            const from = new Date(Date.now() - days * 86400000).toISOString();
+            params['from'] = from;
+        }
+        if (limit)
+            params['take'] = String(limit);
+        const data = await apiGet('/api/v1/incidents', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/organization.js

@@ -0,0 +1,30 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerOrganizationTools(server) {
+    server.tool('get_org_health', 'Get a comprehensive organization health snapshot: DORA performance tier (Elite/High/Medium/Low), cycle time percentile vs industry benchmarks, test coverage percentage, number of active teams, and incident rate. Use this as the first tool to get a high-level picture of engineering health.', {}, async () => {
+        const [doraData, flowData, teamsData] = await Promise.all([
+            apiGet('/api/v1/metrics/dora'),
+            apiGet('/api/v1/flow'),
+            apiGet('/api/v1/teams'),
+        ]);
+        const result = {
+            dora: doraData,
+            flow: flowData,
+            teams: teamsData,
+            _note: 'Use get_dora_summary, get_pr_summary, and list_teams for more detailed breakdowns.',
+        };
+        return { content: [{ type: 'text', text: formatResult(result) }] };
+    });
+    server.tool('get_well_being_summary', 'Get team well-being scores across pillars: focus time (uninterrupted deep work hours), meeting load (percentage of time in meetings), context switching (task interruptions per day), and burnout risk indicators. Use this to understand developer experience and identify teams under stress.', {
+        teamId: z
+            .string()
+            .optional()
+            .describe('Team ID to filter well-being data. Omit for org-wide summary.'),
+    }, async ({ teamId }) => {
+        const params = {};
+        if (teamId)
+            params['teamId'] = teamId;
+        const data = await apiGet('/wellbeing/summary', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/pull-requests.js

@@ -0,0 +1,41 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerPullRequestTools(server) {
+    server.tool('get_pr_summary', 'Get pull request metrics including cycle time (time from first commit to merge), throughput (PRs merged per week), review health (time to first review, reviewer distribution), and PR size trends. Use this to assess code review efficiency.', {
+        teamId: z.string().optional().describe('Team ID to filter to a specific team'),
+        days: z.number().optional().describe('Number of days to look back (default: 30)'),
+    }, async ({ teamId, days }) => {
+        const params = {};
+        if (teamId)
+            params['teamId'] = teamId;
+        if (days) {
+            const from = new Date(Date.now() - days * 86400000).toISOString();
+            params['from'] = from;
+        }
+        const data = await apiGet('/api/v1/review-metrics', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('get_open_prs', 'List currently open pull requests with their age in hours, size (additions + deletions), and reviewer assignments. Use this to identify stale or large PRs that may be blocking the team.', {
+        repositoryId: z.string().optional().describe('Filter to a specific repository by ID'),
+        highRiskOnly: z
+            .boolean()
+            .optional()
+            .describe('If true, only return PRs that are large (>500 lines), old (>72h open), or have no reviewers'),
+    }, async ({ repositoryId, highRiskOnly }) => {
+        const params = { state: 'open' };
+        if (repositoryId)
+            params['repositoryId'] = repositoryId;
+        if (highRiskOnly)
+            params['highRiskOnly'] = 'true';
+        const data = await apiGet('/api/v1/pull-requests', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('get_at_risk_prs', 'Get pull requests at risk of becoming long-running or blocked. These are PRs that have been open for more than 3 days, have no reviews, or are very large. Use this to prompt engineering leads to take action on blocked work.', {}, async () => {
+        const params = {
+            state: 'open',
+            highRiskOnly: 'true',
+        };
+        const data = await apiGet('/api/v1/pull-requests', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/repositories.js

@@ -0,0 +1,24 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerRepositoryTools(server) {
+    server.tool('list_repositories', 'List all repositories connected to Koalr with their health scores, activity levels, and basic stats. Use this to get an overview of the codebase landscape or find repository IDs for filtering.', {
+        limit: z
+            .number()
+            .optional()
+            .describe('Maximum number of repositories to return (default: 50, max: 200)'),
+    }, async ({ limit }) => {
+        const params = {};
+        if (limit)
+            params['limit'] = String(limit);
+        const data = await apiGet('/repositories', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('get_repository', 'Get detailed metrics for a specific repository including deployment frequency, PR cycle time, contributor count, and code health indicators. Use this when asked about a specific codebase.', {
+        name: z
+            .string()
+            .describe('Repository name (e.g. "my-service") or full name with owner (e.g. "org/my-service")'),
+    }, async ({ name }) => {
+        const data = await apiGet('/repositories', { name });
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/search.js

@@ -0,0 +1,17 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerSearchTools(server) {
+    server.tool('search', 'Search across all Koalr entities: developers (by name or GitHub login), repositories (by name), pull requests (by title or branch), and teams (by name). Use this when you need to find an entity before using a more specific tool.', {
+        query: z.string().describe('Search query text (e.g. "payments", "alice", "auth-service")'),
+        type: z
+            .enum(['developer', 'repository', 'pr', 'team'])
+            .optional()
+            .describe('Limit results to a specific entity type. Omit to search all types.'),
+    }, async ({ query, type }) => {
+        const params = { q: query };
+        if (type)
+            params['type'] = type;
+        const data = await apiGet('/search', params);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/dist/tools/teams.js

@@ -0,0 +1,28 @@
+import { z } from 'zod/v3';
+import { apiGet, formatResult } from '../client.js';
+export function registerTeamTools(server) {
+    server.tool('list_teams', 'List all engineering teams in the organization with their member counts and slugs. Use this to discover team IDs needed for filtering other metrics tools.', {}, async () => {
+        const data = await apiGet('/api/v1/teams');
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+    server.tool('get_team', "Get details and metrics for a specific team including DORA performance, cycle time, and member count. Use this when asked about a specific team's engineering health.", {
+        teamId: z.string().describe('The team ID (use list_teams to find team IDs)'),
+    }, async ({ teamId }) => {
+        const [doraData, flowData] = await Promise.all([
+            apiGet('/api/v1/metrics/dora', { teamId }),
+            apiGet('/api/v1/flow', { teamId }),
+        ]);
+        const result = {
+            teamId,
+            dora: doraData,
+            flow: flowData,
+        };
+        return { content: [{ type: 'text', text: formatResult(result) }] };
+    });
+    server.tool('list_team_members', 'List all members of a specific team with their GitHub logins and roles. Use this to understand team composition or find developer logins for the get_developer tool.', {
+        teamId: z.string().describe('The team ID (use list_teams to find team IDs)'),
+    }, async ({ teamId }) => {
+        const data = await apiGet(`/teams/${teamId}/members`);
+        return { content: [{ type: 'text', text: formatResult(data) }] };
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "koalr-mcp",
+  "version": "0.1.0",
+  "description": "Koalr MCP server — connect engineering metrics to AI agents",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "koalr",
+    "mcp",
+    "engineering-metrics",
+    "dora",
+    "deploy-risk"
+  ],
+  "homepage": "https://docs.koalr.com/docs/features/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koalr/koalr-app"
+  },
+  "bin": {
+    "koalr-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}