npm package: @geeks.ltd/geeks-amp-mcp
Description: Local MCP server for AMP (OAuth 2.0 PKCE, token storage, proxy to AMP MCPServer.ashx)
Latest version: 1.0.1

# 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`, `submit_amp_progress_update`, `add_amp_test_case_references`, `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`). Response JSON includes `ampItem.teamPercentageDone` (team board % done) alongside `progress` (workflow stage).
- **submit_amp_progress_update** – Team board: optional `teamPercentageDone` (0, 10, …, 100) and/or `message`; at least one required. Omits `message` when only updating % so AMP can default the comment to `"{n}% completed"`.
- **add_amp_test_case_references** – `ampReference`, required `testCaseReferences` (array of strings), optional `message` after refs; same as AMP “Update test cases” (`[#+REF#]` markers).
- **audit_tdd_amp** – Same as above plus auth status message for `/audit-tdd-amp` flows.