koalr-mcp 0.3.0 → 0.4.0

package/dist/index.js

@@ -17,27 +17,37 @@ async function startHttp() {
     const transports = new Map();
     const httpServer = createHttpServer(async (req, res) => {
         const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+        // CORS — required for browser-based MCP clients (Claude.ai web)
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Mcp-Session-Id');
+        res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
         // Health check (no auth required)
         if (req.method === 'GET' && url.pathname === '/health') {
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ status: 'ok', server: 'koalr-mcp' }));
             return;
         }
-        // Route: /{apiKey}/mcp  — per-user hosted endpoint
-        // Route: /mcp           — env-var key (for local/self-hosted use)
-        let mcpPath = '/mcp';
+        // Route: /mcp?apiKey=koalr_xxx  — Smithery gateway style (query param)
+        // Route: /{apiKey}/mcp          — path-based per-user endpoint
+        // Route: /mcp                   — env-var key (local/self-hosted)
         let sessionApiKey;
         const pathParts = url.pathname.split('/').filter(Boolean);
-        if (pathParts.length === 2 && pathParts[1] === 'mcp') {
-            // /{apiKey}/mcp
-            sessionApiKey = pathParts[0];
-            mcpPath = `/${pathParts[0]}/mcp`;
+        const isMcpEndpoint = (pathParts.length === 1 && pathParts[0] === 'mcp') ||
+            (pathParts.length === 2 && pathParts[1] === 'mcp');
+        // API key precedence: query param > path segment > env var
+        if (url.searchParams.has('apiKey')) {
+            sessionApiKey = url.searchParams.get('apiKey') ?? undefined;
         }
-        else if (pathParts.length === 1 && pathParts[0] === 'mcp') {
-            // /mcp — use env key
-            mcpPath = '/mcp';
+        else if (pathParts.length === 2 && pathParts[1] === 'mcp') {
+            sessionApiKey = pathParts[0];
         }
-        if (url.pathname === mcpPath) {
+        if (isMcpEndpoint) {
             if (req.method === 'POST') {
                 const sessionId = req.headers['mcp-session-id'] ?? undefined;
                 let transport;

package/dist/server.js

@@ -10,10 +10,35 @@ 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';
+const SYSTEM_PROMPT = `You are connected to Koalr, a deployment intelligence platform for engineering teams.
+
+## What this server does
+Koalr tracks pull requests, DORA metrics, deploy risk, test coverage, incidents, and developer productivity across GitHub-connected repositories. All tools are read-only.
+
+## When to use which tool
+- **Broad overview**: start with get_org_health
+- **Merge safety**: use score_pr_for_deploy_risk — pass the PR number, file list, and size
+- **Delivery performance**: get_dora_summary (or get_dora_trend for week-over-week changes)
+- **Stale/blocked work**: get_at_risk_prs then get_open_prs for detail
+- **Team or repo drill-down**: list_teams → get_team, or list_repositories → get_repository
+- **Individual developer**: get_developer (requires GitHub login) or list_top_contributors
+- **Incidents**: list_recent_incidents returns MTTR and impact
+- **Coverage**: get_coverage_summary by repository
+- **AI tool usage**: get_ai_adoption_summary or get_ai_adoption_trend
+
+## Key parameters
+- Most tools accept optional \`from\`/\`to\` ISO date strings to set the time window (default: last 30 days)
+- Use \`teamId\` to scope metrics to a specific team — call list_teams first to find IDs
+- Use \`repositoryId\` to scope metrics to a single repo — call list_repositories first
+
+## Risk score interpretation
+score_pr_for_deploy_risk returns 0–100. 0–39 = low, 40–69 = medium, 70–89 = high, 90–100 = critical. Scores above 70 warrant a review before merging.`;
 export function createServer(apiKey) {
     const server = new McpServer({
         name: 'koalr',
-        version: '0.3.0',
+        version: '0.3.2',
+    }, {
+        instructions: SYSTEM_PROMPT,
     });
     // Register all tool groups (apiKey is threaded through for hosted HTTP mode)
     registerDoraTools(server, apiKey);

package/dist/tools/ai-adoption.js

@@ -1,7 +1,7 @@
 import { z } from 'zod/v3';
 import { apiGet, formatResult } from '../client.js';
 export function registerAiAdoptionTools(server, apiKey) {
-    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 () => {
+    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.', {}, { readOnlyHint: true }, async () => {
         const data = await apiGet('/api/v1/copilot', undefined, apiKey);
         return { content: [{ type: 'text', text: formatResult(data) }] };
     });
@@ -10,7 +10,7 @@ export function registerAiAdoptionTools(server, apiKey) {
             .number()
             .optional()
             .describe('Number of days to look back for trend data (default: 90)'),
-    }, async ({ days }) => {
+    }, { readOnlyHint: true }, async ({ days }) => {
         const params = {};
         if (days)
             params['days'] = String(days);

package/dist/tools/coverage.js

@@ -6,7 +6,7 @@ export function registerCoverageTools(server, apiKey) {
             .string()
             .optional()
             .describe('Filter to a specific repository by ID. Omit to see all repositories.'),
-    }, async ({ repositoryId }) => {
+    }, { readOnlyHint: true }, async ({ repositoryId }) => {
         const params = {};
         if (repositoryId)
             params['repositoryId'] = repositoryId;

package/dist/tools/deploy-risk.js

@@ -24,7 +24,7 @@ export function registerDeployRiskTools(server, apiKey) {
             .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, }) => {
+    }, { readOnlyHint: true }, 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,

package/dist/tools/developers.js

@@ -3,7 +3,7 @@ import { apiGet, formatResult } from '../client.js';
 export function registerDeveloperTools(server, apiKey) {
     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 }) => {
+    }, { readOnlyHint: true }, async ({ login }) => {
         const data = await apiGet('/developer-profiles', { login }, apiKey);
         return { content: [{ type: 'text', text: formatResult(data) }] };
     });
@@ -13,7 +13,7 @@ export function registerDeveloperTools(server, apiKey) {
             .number()
             .optional()
             .describe('Number of contributors to return (default: 10, max: 50)'),
-    }, async ({ days, limit }) => {
+    }, { readOnlyHint: true }, async ({ days, limit }) => {
         const params = {};
         if (days)
             params['days'] = String(days);

package/dist/tools/dora.js

@@ -11,7 +11,7 @@ export function registerDoraTools(server, apiKey) {
             .string()
             .optional()
             .describe('End date as ISO string (e.g. 2024-01-31). Defaults to today.'),
-    }, async ({ teamId, from, to }) => {
+    }, { readOnlyHint: true }, async ({ teamId, from, to }) => {
         const params = {};
         if (teamId)
             params['teamId'] = teamId;
@@ -31,7 +31,7 @@ export function registerDoraTools(server, apiKey) {
             .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 }) => {
+    }, { readOnlyHint: true }, async ({ metric, days, teamId }) => {
         const params = { metric };
         if (days)
             params['days'] = String(days);

package/dist/tools/incidents.js

@@ -7,7 +7,7 @@ export function registerIncidentTools(server, apiKey) {
             .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 }) => {
+    }, { readOnlyHint: true }, async ({ days, limit }) => {
         const params = {};
         if (days) {
             const from = new Date(Date.now() - days * 86400000).toISOString();

package/dist/tools/organization.js

@@ -1,7 +1,7 @@
 import { z } from 'zod/v3';
 import { apiGet, formatResult } from '../client.js';
 export function registerOrganizationTools(server, apiKey) {
-    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 () => {
+    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.', {}, { readOnlyHint: true }, async () => {
         const [doraData, flowData, teamsData] = await Promise.all([
             apiGet('/api/v1/metrics/dora', undefined, apiKey),
             apiGet('/api/v1/flow', undefined, apiKey),
@@ -20,7 +20,7 @@ export function registerOrganizationTools(server, apiKey) {
             .string()
             .optional()
             .describe('Team ID to filter well-being data. Omit for org-wide summary.'),
-    }, async ({ teamId }) => {
+    }, { readOnlyHint: true }, async ({ teamId }) => {
         const params = {};
         if (teamId)
             params['teamId'] = teamId;

package/dist/tools/pull-requests.js

@@ -4,7 +4,7 @@ export function registerPullRequestTools(server, apiKey) {
     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 }) => {
+    }, { readOnlyHint: true }, async ({ teamId, days }) => {
         const params = {};
         if (teamId)
             params['teamId'] = teamId;
@@ -21,7 +21,7 @@ export function registerPullRequestTools(server, apiKey) {
             .boolean()
             .optional()
             .describe('If true, only return PRs that are large (>500 lines), old (>72h open), or have no reviewers'),
-    }, async ({ repositoryId, highRiskOnly }) => {
+    }, { readOnlyHint: true }, async ({ repositoryId, highRiskOnly }) => {
         const params = { state: 'open' };
         if (repositoryId)
             params['repositoryId'] = repositoryId;
@@ -30,7 +30,7 @@ export function registerPullRequestTools(server, apiKey) {
         const data = await apiGet('/api/v1/pull-requests', params, apiKey);
         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 () => {
+    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.', {}, { readOnlyHint: true }, async () => {
         const params = {
             state: 'open',
             highRiskOnly: 'true',

package/dist/tools/repositories.js

@@ -6,7 +6,7 @@ export function registerRepositoryTools(server, apiKey) {
             .number()
             .optional()
             .describe('Maximum number of repositories to return (default: 50, max: 200)'),
-    }, async ({ limit }) => {
+    }, { readOnlyHint: true }, async ({ limit }) => {
         const params = {};
         if (limit)
             params['limit'] = String(limit);
@@ -17,7 +17,7 @@ export function registerRepositoryTools(server, apiKey) {
         name: z
             .string()
             .describe('Repository name (e.g. "my-service") or full name with owner (e.g. "org/my-service")'),
-    }, async ({ name }) => {
+    }, { readOnlyHint: true }, async ({ name }) => {
         const data = await apiGet('/repositories', { name }, apiKey);
         return { content: [{ type: 'text', text: formatResult(data) }] };
     });

package/dist/tools/search.js

@@ -7,7 +7,7 @@ export function registerSearchTools(server, apiKey) {
             .enum(['developer', 'repository', 'pr', 'team'])
             .optional()
             .describe('Limit results to a specific entity type. Omit to search all types.'),
-    }, async ({ query, type }) => {
+    }, { readOnlyHint: true }, async ({ query, type }) => {
         const params = { q: query };
         if (type)
             params['type'] = type;

package/dist/tools/teams.js

@@ -1,13 +1,13 @@
 import { z } from 'zod/v3';
 import { apiGet, formatResult } from '../client.js';
 export function registerTeamTools(server, apiKey) {
-    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 () => {
+    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.', {}, { readOnlyHint: true }, async () => {
         const data = await apiGet('/api/v1/teams', undefined, apiKey);
         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 }) => {
+    }, { readOnlyHint: true }, async ({ teamId }) => {
         const [doraData, flowData] = await Promise.all([
             apiGet('/api/v1/metrics/dora', { teamId }, apiKey),
             apiGet('/api/v1/flow', { teamId }, apiKey),
@@ -21,7 +21,7 @@ export function registerTeamTools(server, apiKey) {
     });
     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 }) => {
+    }, { readOnlyHint: true }, async ({ teamId }) => {
         const data = await apiGet(`/teams/${teamId}/members`, undefined, apiKey);
         return { content: [{ type: 'text', text: formatResult(data) }] };
     });

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "koalr-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Koalr MCP server — connect engineering metrics to AI agents",
   "type": "module",
   "license": "MIT",
   "keywords": [
-    "koalr",
     "mcp",
+    "koalr",
     "engineering-metrics",
     "dora",
-    "deploy-risk"
+    "deploy-risk",
+    "devops",
+    "github",
+    "pull-requests",
+    "code-review",
+    "developer-productivity",
+    "deployment",
+    "metrics",
+    "ai-agent",
+    "claude",
+    "model-context-protocol"
   ],
   "homepage": "https://docs.koalr.com/docs/features/mcp-server",
   "repository": {