@geeks.ltd/geeks-amp-mcp 1.0.0

package/README.md

@@ -0,0 +1,69 @@
+# Geeks AMP MCP Server
+
+Local MCP server for Cursor that authenticates to your AMP backend via OAuth 2.0 (Authorization Code + PKCE) and proxies tool calls to AMP’s `MCPServer.ashx`.
+
+## Flow
+
+1. **First use** – When you call an AMP tool, the server opens your browser to AMP’s login. After you sign in, AMP redirects to `http://127.0.0.1:5005/callback`. The server exchanges the code for access and refresh tokens and stores them (e.g. in `~/.amp-mcp/credentials.json`).
+2. **Later uses** – The server reuses the stored access token. When it expires, it uses the refresh token; if refresh fails, it runs the browser flow again.
+3. **Tools** – `get_projects`, `get_amp_item_with_test_cases`, `get_auth_status`, `audit_tdd_amp` are forwarded to AMP with `Authorization: Bearer <token>`.
+
+## Prerequisites
+
+- Node.js 18+
+- AMP running with OAuth client `amp-cursor-mcp` and redirect URI `http://127.0.0.1:5005/callback` (see `Website/web.config`).
+
+## Setup
+
+```bash
+cd geeks-amp-mcp
+npm install
+npm run build
+```
+
+## Cursor config
+
+In `.cursor/mcp.json` (project or global), use the **local server** via npx (no env token). From the repo root (`geeksamp`), run the package with:
+
+```json
+{
+  "mcpServers": {
+    "amp": {
+      "command": "npx",
+      "args": ["./geeks-amp-mcp"],
+      "env": {
+        "AMP_BASE_URL": "http://localhost:39290",
+        "AMP_OAUTH_CLIENT_ID": "amp-cursor-mcp",
+        "AMP_CALLBACK_PORT": "5005"
+      }
+    }
+  }
+}
+```
+
+- **`npx ./geeks-amp-mcp`** – Runs the local package’s bin (uses `geeks-amp-mcp/dist/index.js`). Cursor’s working directory is the workspace root, so the path is relative to that. Restart Cursor after changing MCP config.
+- To use an absolute path instead: `"args": ["C:\\path\\to\\geeksamp\\geeks-amp-mcp"]` with `"command": "npx"`, or `"command": "node"` and `"args": ["C:\\path\\to\\geeksamp\\geeks-amp-mcp\\dist\\index.js"]`.
+- **Plain `npx geeks-amp-mcp`** (no path) only works if the package is installed from npm. If you publish `geeks-amp-mcp` to the registry, users can run `npx geeks-amp-mcp` from any directory and set `AMP_BASE_URL` etc. in env.
+
+## Publishing to npm
+
+1. Create an account at [npmjs.com](https://www.npmjs.com/signup).
+2. In `geeks-amp-mcp`, run `npm run build`, then `npm login` and `npm publish`.
+3. If the name `geeks-amp-mcp` is taken, use a scoped name in `package.json` (e.g. `"name": "@your-org/geeks-amp-mcp"`); then publish with `npm publish --access public` so others can install it without a paid plan.
+4. Update `package.json` `repository.url` (replace `YOUR_ORG` with your GitHub org/user) before publishing.
+
+## Env (optional)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AMP_BASE_URL` | `http://localhost:39290` | AMP base URL |
+| `AMP_OAUTH_CLIENT_ID` | `amp-cursor-mcp` | OAuth client id (must match AMP) |
+| `AMP_CALLBACK_PORT` | `5005` | Callback listener port (must be in AMP redirect URIs) |
+| `AMP_MCP_CREDENTIALS_DIR` | `~/.amp-mcp` | Directory for stored tokens |
+
+## Tools
+
+- **get_auth_status** – Returns `Authenticated: YES` or `Authenticated: NO` (no browser).
+- **get_projects** – List AMP projects (optional `searchTerm`, `limit`).
+- **get_amp_item_with_test_cases** – AMP item + test case refs by `ampReference` (e.g. `12345` or `AMP-12345`).
+- **audit_tdd_amp** – Same as above plus auth status message for `/audit-tdd-amp` flows.

package/bin/geeks-amp-mcp.cjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Launcher so the MCP server is always run with Node (avoids Windows running .js with WScript).
+ * npm/npx runs this as "node bin/geeks-amp-mcp.cjs", which then runs "node dist/index.js".
+ */
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const dir = __dirname;
+const script = path.join(dir, "..", "dist", "index.js");
+
+const result = spawnSync(process.execPath, [script], {
+  stdio: "inherit",
+  windowsHide: true,
+  cwd: path.join(dir, ".."),
+});
+
+process.exitCode = result.status != null ? result.status : 1;

package/dist/auth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OAuth 2.0 Authorization Code + PKCE for AMP backend.
+ * Matches AMP endpoints: GET /api/oauth/authorize, POST /api/oauth/token.
+ * Uses http://127.0.0.1:5005/callback (per AMP web.config).
+ */
+export interface TokenData {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    token_type?: string;
+}
+export interface StoredCredentials {
+    access_token: string;
+    refresh_token?: string;
+    expires_at: number;
+}
+export declare function getAmpBaseUrl(): string;
+/**
+ * Return a valid access token. If none or expired, try refresh; if that fails, run full OAuth flow (browser).
+ */
+export declare function ensureAccessToken(): Promise<string>;
+/**
+ * Current auth status without triggering login. For "Authenticated: YES/NO" in Cursor chat.
+ */
+export declare function getAuthStatus(): {
+    authenticated: boolean;
+    message: string;
+};

package/dist/auth.js

@@ -0,0 +1,211 @@
+/**
+ * OAuth 2.0 Authorization Code + PKCE for AMP backend.
+ * Matches AMP endpoints: GET /api/oauth/authorize, POST /api/oauth/token.
+ * Uses http://127.0.0.1:5005/callback (per AMP web.config).
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as http from "http";
+import * as os from "os";
+import * as path from "path";
+import open from "open";
+const CALLBACK_PORT = parseInt(process.env.AMP_CALLBACK_PORT ?? "5005", 10);
+const CALLBACK_PATH = "/callback";
+const CLIENT_ID = process.env.AMP_OAUTH_CLIENT_ID ?? "amp-cursor-mcp";
+const SCOPE = process.env.AMP_OAUTH_SCOPE ?? "api.read api.write";
+const REFRESH_BUFFER_MS = 60 * 1000; // treat as expired 1 min early
+function getCredentialsPath() {
+    const dir = process.env.AMP_MCP_CREDENTIALS_DIR ?? path.join(os.homedir(), ".amp-mcp");
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { mode: 0o700 });
+    }
+    catch {
+        return path.join(process.cwd(), ".amp-mcp-credentials.json");
+    }
+    return path.join(dir, "credentials.json");
+}
+function randomBase64Url(bytes) {
+    return crypto.randomBytes(bytes).toString("base64url");
+}
+function sha256Base64Url(input) {
+    return crypto.createHash("sha256").update(input, "utf8").digest("base64url");
+}
+export function getAmpBaseUrl() {
+    const base = process.env.AMP_BASE_URL ?? "http://localhost:39290";
+    return base.replace(/\/$/, "");
+}
+function loadCredentials() {
+    try {
+        const p = getCredentialsPath();
+        if (!fs.existsSync(p))
+            return null;
+        const raw = fs.readFileSync(p, "utf8");
+        const data = JSON.parse(raw);
+        if (data?.access_token && typeof data.expires_at === "number")
+            return data;
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function saveCredentials(creds) {
+    const p = getCredentialsPath();
+    try {
+        fs.writeFileSync(p, JSON.stringify(creds, null, 0), { mode: 0o600 });
+    }
+    catch (e) {
+        console.error("Failed to save credentials:", e);
+    }
+}
+/**
+ * Start local HTTP server, open browser to AMP authorize, receive callback, exchange code for tokens.
+ */
+function runOAuthFlow() {
+    const state = randomBase64Url(24);
+    const codeVerifier = randomBase64Url(32);
+    const codeChallenge = sha256Base64Url(codeVerifier);
+    const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
+    const baseUrl = getAmpBaseUrl();
+    const authorizeUrl = `${baseUrl}/api/oauth/authorize?` +
+        new URLSearchParams({
+            client_id: CLIENT_ID,
+            response_type: "code",
+            redirect_uri: redirectUri,
+            scope: SCOPE,
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        }).toString();
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const reqUrl = req.url ?? "/";
+            const url = new URL(reqUrl, `http://127.0.0.1:${CALLBACK_PORT}`);
+            if (url.pathname !== CALLBACK_PATH) {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const returnedState = url.searchParams.get("state");
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            if (returnedState !== state) {
+                res.writeHead(400);
+                res.end("<h1>Invalid state</h1><p>You can close this window.</p>");
+                server.close();
+                reject(new Error("OAuth state mismatch"));
+                return;
+            }
+            if (!code) {
+                const err = url.searchParams.get("error") ?? "missing code";
+                res.writeHead(400);
+                res.end(`<h1>Authorization failed</h1><p>${err}</p><p>You can close this window.</p>`);
+                server.close();
+                reject(new Error(`OAuth error: ${err}`));
+                return;
+            }
+            res.writeHead(200);
+            res.end("<h1>Success</h1><p>You are authenticated. You can close this window and return to Cursor.</p>");
+            server.close();
+            exchangeCodeForTokens(code, codeVerifier, redirectUri)
+                .then(resolve)
+                .catch(reject);
+        });
+        server.listen(CALLBACK_PORT, "127.0.0.1", () => {
+            open(authorizeUrl);
+        });
+        server.on("error", (err) => {
+            reject(err);
+        });
+    });
+}
+function exchangeCodeForTokens(code, codeVerifier, redirectUri) {
+    const baseUrl = getAmpBaseUrl();
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: CLIENT_ID,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+    }).toString();
+    return fetch(`${baseUrl}/api/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    })
+        .then((r) => {
+        if (!r.ok)
+            return r.text().then((t) => Promise.reject(new Error(`Token exchange failed: ${r.status} ${t}`)));
+        return r.json();
+    })
+        .then((data) => {
+        const expiresAt = Date.now() + (data.expires_in ?? 3600) * 1000;
+        saveCredentials({
+            access_token: data.access_token,
+            refresh_token: data.refresh_token,
+            expires_at: expiresAt,
+        });
+        return data.access_token;
+    });
+}
+function refreshAccessToken() {
+    const creds = loadCredentials();
+    if (!creds?.refresh_token)
+        return Promise.reject(new Error("No refresh token"));
+    const baseUrl = getAmpBaseUrl();
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: CLIENT_ID,
+        refresh_token: creds.refresh_token,
+    }).toString();
+    return fetch(`${baseUrl}/api/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    })
+        .then((r) => {
+        if (!r.ok)
+            return r
+                .text()
+                .then((t) => Promise.reject(new Error(`Refresh failed: ${r.status} ${t}`)));
+        return r.json();
+    })
+        .then((data) => {
+        const expiresAt = Date.now() + (data.expires_in ?? 3600) * 1000;
+        saveCredentials({
+            access_token: data.access_token,
+            refresh_token: data.refresh_token ?? creds.refresh_token,
+            expires_at: expiresAt,
+        });
+        return data.access_token;
+    });
+}
+/**
+ * Return a valid access token. If none or expired, try refresh; if that fails, run full OAuth flow (browser).
+ */
+export async function ensureAccessToken() {
+    const creds = loadCredentials();
+    if (creds && Date.now() < creds.expires_at - REFRESH_BUFFER_MS)
+        return creds.access_token;
+    if (creds?.refresh_token) {
+        try {
+            return await refreshAccessToken();
+        }
+        catch {
+            // fall through to full flow
+        }
+    }
+    return runOAuthFlow();
+}
+/**
+ * Current auth status without triggering login. For "Authenticated: YES/NO" in Cursor chat.
+ */
+export function getAuthStatus() {
+    const creds = loadCredentials();
+    const valid = !!creds && Date.now() < creds.expires_at - REFRESH_BUFFER_MS;
+    return {
+        authenticated: valid,
+        message: valid ? "Authenticated: YES" : "Authenticated: NO",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Geeks AMP MCP server – local stdio server for Cursor.
+ * Performs OAuth 2.0 PKCE with AMP (browser login, callback, token storage/refresh),
+ * then proxies tool calls to AMP's MCPServer.ashx with Bearer token.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,76 @@
+/**
+ * Geeks AMP MCP server – local stdio server for Cursor.
+ * Performs OAuth 2.0 PKCE with AMP (browser login, callback, token storage/refresh),
+ * then proxies tool calls to AMP's MCPServer.ashx with Bearer token.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ensureAccessToken, getAuthStatus } from "./auth.js";
+import { callAmpTool } from "./tools.js";
+async function main() {
+    const server = new McpServer({
+        name: "geeks-amp-mcp",
+        version: "1.0.0",
+    });
+    // get_auth_status – no AMP call; report stored auth state
+    server.tool("get_auth_status", "Report whether the MCP server is authenticated to AMP. Returns 'Authenticated: YES' or 'Authenticated: NO' without opening the browser.", {}, async () => {
+        const status = getAuthStatus();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        authenticated: status.authenticated,
+                        message: status.message,
+                    }),
+                },
+            ],
+        };
+    });
+    // get_projects – ensure token, then call AMP
+    server.tool("get_projects", "Get a list of projects with their ID and Name from AMP.", {
+        searchTerm: z.string().optional().describe("Optional search term to filter projects by name or ID"),
+        limit: z.number().optional().describe("Maximum number of projects to return (default: 100)"),
+    }, async ({ searchTerm, limit, }) => {
+        const token = await ensureAccessToken();
+        const args = {};
+        if (searchTerm !== undefined)
+            args.searchTerm = searchTerm;
+        if (limit !== undefined)
+            args.limit = limit;
+        return callAmpTool("get_projects", args, token);
+    });
+    // get_amp_item_with_test_cases – ensure token, then call AMP
+    server.tool("get_amp_item_with_test_cases", "Get AMP (work item) details and all its test case references for a given AMP item. Use the reference number (e.g. 12345) or AMP-12345 format. Returns subject, note, status, progress, project, and a list of test case references (e.g. +AVFD) with the comment they appear in.", {
+        ampReference: z.string().describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
+    }, async ({ ampReference }) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("get_amp_item_with_test_cases", { ampReference }, token);
+    });
+    // Optional: audit-tdd-amp – get AMP item + test cases and report auth status (for /audit-tdd-amp in Cursor)
+    server.tool("audit_tdd_amp", "Get AMP item and its test case references, and report auth status. Use for /audit-tdd-amp flows in Cursor.", {
+        ampReference: z.string().describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
+    }, async ({ ampReference }) => {
+        const token = await ensureAccessToken();
+        const result = await callAmpTool("get_amp_item_with_test_cases", { ampReference }, token);
+        const status = getAuthStatus();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: status.message,
+                        ampItemAndTestCases: result.content[0]?.text,
+                    }),
+                },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[geeks-amp-mcp] Startup error:", err?.message ?? err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tool definitions and AMP MCPServer.ashx proxy.
+ * All AMP tools require a valid Bearer token (obtained via auth.ensureAccessToken).
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+        }>;
+        required?: string[];
+    };
+}
+export declare const TOOL_DEFINITIONS: ToolDefinition[];
+export interface AmpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Call AMP's MCPServer.ashx tools/call with the given Bearer token.
+ * Returns MCP-style content array; on HTTP or JSON-RPC error returns error content.
+ */
+export declare function callAmpTool(toolName: string, args: Record<string, unknown>, accessToken: string): Promise<AmpToolResult>;

package/dist/tools.js

@@ -0,0 +1,105 @@
+/**
+ * Tool definitions and AMP MCPServer.ashx proxy.
+ * All AMP tools require a valid Bearer token (obtained via auth.ensureAccessToken).
+ */
+import { getAmpBaseUrl } from "./auth.js";
+export const TOOL_DEFINITIONS = [
+    {
+        name: "get_projects",
+        description: "Get a list of projects with their ID and Name from AMP.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                searchTerm: {
+                    type: "string",
+                    description: "Optional search term to filter projects by name or ID",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of projects to return (default: 100)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_amp_item_with_test_cases",
+        description: "Get AMP (work item) details and all its test case references for a given AMP item. Use the reference number (e.g. 12345) or AMP-12345 format. Returns subject, note, status, progress, project, and a list of test case references (e.g. +AVFD) with the comment they appear in.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP item reference number, e.g. '12345' or 'AMP-12345'",
+                },
+            },
+            required: ["ampReference"],
+        },
+    },
+    {
+        name: "get_auth_status",
+        description: "Report whether the MCP server is authenticated to AMP. Returns 'Authenticated: YES' or 'Authenticated: NO' without opening the browser.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+];
+/**
+ * Call AMP's MCPServer.ashx tools/call with the given Bearer token.
+ * Returns MCP-style content array; on HTTP or JSON-RPC error returns error content.
+ */
+export async function callAmpTool(toolName, args, accessToken) {
+    const baseUrl = getAmpBaseUrl();
+    const url = `${baseUrl}/Services/MCPServer.ashx`;
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+    });
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${accessToken}`,
+        },
+        body,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: `AMP request failed: ${res.status}`,
+                        body: text,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const json = (await res.json());
+    if (json.error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: json.error.message ?? json.error,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const result = json.result;
+    if (result?.content && Array.isArray(result.content))
+        return { content: result.content };
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result ?? json) },
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@geeks.ltd/geeks-amp-mcp",
+  "version": "1.0.0",
+  "description": "Local MCP server for AMP (OAuth 2.0 PKCE, token storage, proxy to AMP MCPServer.ashx)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "geeks-amp-mcp": "./bin/geeks-amp-mcp.cjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --import tsx src/index.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "amp",
+    "oauth",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/geeks-ltd/geeks.amp.mcp",
+    "directory": "geeks-amp-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "open": "^10.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}