@attackforge/mcp-server 0.2.9 → 0.3.1

package/README.md

@@ -1,24 +1,13 @@
 # AttackForge MCP Server
 
-An MCP (Model Context Protocol) server that enables Claude AI to interact with AttackForge. This server acts as a proxy, forwarding tool requests from Claude to your AttackForge instance.
+An MCP (Model Context Protocol) server that gives any MCP client access to AttackForge. It acts as a proxy, forwarding the client's tool requests to your AttackForge instance.
 
 ## Installation
 
-### From npm
-
 ```bash
 npm install -g @attackforge/mcp-server
 ```
 
-### From source
-
-```bash
-git clone https://github.com/AttackForge/af-mcp-server.git
-cd af-mcp-server
-npm install
-npm run build
-```
-
 ## Configuration
 
 The server requires the following environment variables:
@@ -28,15 +17,18 @@ The server requires the following environment variables:
 | `AF_HOSTNAME` | Yes | Your AttackForge server hostname (e.g., `your-instance.attackforge.com`) |
 | `AF_USER_KEY` | Yes | Your AttackForge API user key for authentication |
 | `AF_PORT` | No | Custom port if your AttackForge server uses a non-standard HTTPS port |
+| `AF_TIMEOUT_MS` | No | How long to wait on an AttackForge request before giving up (default `60000`) |
 
 ## Usage
 
+The server communicates over stdio, so any MCP client that launches local (stdio) servers can use it. Configure the client to run the `af-mcp-server` command with the environment variables above. Configuration for two common clients is shown below; for other clients, see their documentation on adding a stdio server.
+
 ### Claude Desktop
 
 Add to your Claude Desktop configuration file:
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -54,20 +46,8 @@ Add to your Claude Desktop configuration file:
 
 ### Claude Code
 
-Add to your Claude Code settings:
-
-```json
-{
-  "mcpServers": {
-    "attackforge": {
-      "command": "af-mcp-server",
-      "env": {
-        "AF_HOSTNAME": "your-instance.attackforge.com",
-        "AF_USER_KEY": "your-api-key"
-      }
-    }
-  }
-}
+```bash
+claude mcp add attackforge -e AF_HOSTNAME=your-instance.attackforge.com -e AF_USER_KEY=your-api-key -- af-mcp-server
 ```
 
 ### Running directly
@@ -76,16 +56,41 @@ Add to your Claude Code settings:
 AF_HOSTNAME=your-instance.attackforge.com AF_USER_KEY=your-api-key af-mcp-server
 ```
 
+The server then waits for an MCP client on stdin and stdout; this is mainly useful for checking the configuration starts cleanly.
+
 ## How It Works
 
 This MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io/) and proxies requests to your AttackForge instance:
 
-1. Claude connects to the server via stdio transport
-2. When Claude lists available tools, the server fetches them from `https://{AF_HOSTNAME}/mcp/tools/list`
-3. When Claude calls a tool, the server forwards the request to `https://{AF_HOSTNAME}/mcp/tools/call`
+1. The MCP client starts the server and connects to it over stdio
+2. When the client lists available tools, the server fetches them from `https://{AF_HOSTNAME}/mcp/tools/list`
+3. When the client calls a tool, the server forwards the request to `https://{AF_HOSTNAME}/mcp/tools/call`
 4. All requests are authenticated using the `x-user-key` header
 
-The tools available to Claude are determined by your AttackForge instance configuration.
+The tools available are determined by your AttackForge instance configuration and the permissions of the user whose key is configured.
+
+### Protocol versions
+
+The server is built on the v2 MCP TypeScript SDK (`@modelcontextprotocol/server`) and serves both protocol eras from the same connection entry point:
+
+- **Modern** — the `2026-07-28` revision, negotiated with `server/discover`
+- **Legacy** — the `2024-10-07` through `2025-11-25` revisions, negotiated with the `initialize` handshake
+
+The era is decided once per connection and every tool behaves identically on both, so no configuration is needed to support either kind of client.
+
+### Errors
+
+Failures reaching AttackForge are relayed as MCP protocol errors naming the actual cause:
+
+| Status | Meaning |
+|--------|---------|
+| `400` | AttackForge rejected the request; the validation detail is included in the message |
+| `401` | `AF_USER_KEY` is not a valid AttackForge API key |
+| `404` | Local MCP access is disabled on the instance, or the user has no access to the MCP module |
+| other | Relayed with the status and response body |
+| none | AttackForge could not be reached, or did not respond within `AF_TIMEOUT_MS` |
+
+A tool that runs but fails (for example, a record that does not exist) returns an ordinary tool result marked `isError`, which is passed through unchanged for the model to read.
 
 ## Development
 
@@ -103,6 +108,20 @@ npm run clean
 npm run rebuild
 ```
 
+### Testing
+
+```bash
+# Contract tests: the built server against a mock AttackForge, on both protocol eras
+npm test
+
+# Integration tests against a real AttackForge instance
+npm run test:integration
+```
+
+The tests are TypeScript run directly by Node, which needs Node.js 22.18 or later.
+
+Integration tests read `AF_HOSTNAME`, `AF_USER_KEY` and optionally `AF_PORT` and `AF_TIMEOUT_MS` from a gitignored `.env.integration` - copy `.env.integration.example` to start. They are skipped when those are not set, and are read-only unless `AF_TEST_ALLOW_WRITES=true`, which creates a tagged testsuite per protocol era on each run.
+
 ## Requirements
 
 - Node.js 22 or later

package/dist/index.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ProtocolError, ProtocolErrorCode, Server } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { readFile } from 'node:fs/promises';
 if (!process.env.AF_HOSTNAME) {
     throw new Error('Environment variable AF_HOSTNAME is required');
@@ -9,6 +8,7 @@ if (!process.env.AF_HOSTNAME) {
 if (!process.env.AF_USER_KEY) {
     throw new Error('Environment variable AF_USER_KEY is required');
 }
+const DEFAULT_TIMEOUT_MS = 60_000;
 let packageJson;
 try {
     const filePath = new URL('../package.json', import.meta.url);
@@ -18,50 +18,83 @@ try {
 catch (err) {
     throw new Error('Failed to parse package.json');
 }
-const mcpServer = new McpServer({
-    name: packageJson.name,
-    version: packageJson.version,
-}, {
-    capabilities: {
-        tools: {
-            listChanged: false
-        }
+function timeoutMs() {
+    const configured = Number(process.env.AF_TIMEOUT_MS);
+    return (Number.isFinite(configured) && configured > 0) ? configured : DEFAULT_TIMEOUT_MS;
+}
+// The AttackForge endpoints report failures through the HTTP status, so map each
+// one back to a message that names the actual cause instead of a generic error.
+function describeFailure(status, body) {
+    switch (status) {
+        case 400:
+            return `AttackForge rejected the request${body ? `: ${body}` : ''}`;
+        case 401:
+            return 'AttackForge rejected the credentials - AF_USER_KEY is not a valid API key';
+        case 404:
+            return 'The AttackForge MCP module is unavailable - local MCP access is disabled on this instance, or this user has no access to the module';
+        default:
+            return `AttackForge returned ${status}${body ? `: ${body}` : ''}`;
     }
-});
-mcpServer.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const url = new URL('/mcp/tools/call', `https://${process.env.AF_HOSTNAME}`);
+}
+async function forward(path, request) {
+    const url = new URL(path, `https://${process.env.AF_HOSTNAME}`);
     if (process.env.AF_PORT) {
         url.port = process.env.AF_PORT;
     }
-    const response = await fetch(url, {
-        method: 'POST',
-        body: JSON.stringify(request),
-        headers: {
-            'content-type': 'application/json',
-            'x-user-key': process.env.AF_USER_KEY,
-        }
-    });
-    if (response.status === 200) {
-        return await response.json();
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            body: JSON.stringify(request),
+            headers: {
+                'content-type': 'application/json',
+                'x-user-key': process.env.AF_USER_KEY,
+            },
+            signal: AbortSignal.timeout(timeoutMs()),
+        });
     }
-    throw new Error('Tool not found');
-});
-mcpServer.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
-    const url = new URL('/mcp/tools/list', `https://${process.env.AF_HOSTNAME}`);
-    if (process.env.AF_PORT) {
-        url.port = process.env.AF_PORT;
+    catch (err) {
+        throw new ProtocolError(ProtocolErrorCode.InternalError, `Could not reach AttackForge at ${url.host}: ${(err instanceof Error) ? err.message : String(err)}`);
+    }
+    if (!response.ok) {
+        throw new ProtocolError(ProtocolErrorCode.InternalError, describeFailure(response.status, (await response.text()).trim()));
     }
-    const response = await fetch(url, {
-        method: 'POST',
-        body: JSON.stringify(request),
-        headers: {
-            'content-type': 'application/json',
-            'x-user-key': process.env.AF_USER_KEY,
+    return await response.json();
+}
+// The low-level Server is @deprecated in favour of McpServer, but its note carves
+// out advanced use cases and a pure proxy is one: the tools come from AttackForge
+// at runtime, so there is nothing to registerTool and nothing to derive a schema
+// from. What the low-level path owes the SDK is projectCallToolResult, which
+// McpServer would otherwise call for us - the AttackForge REST endpoints return
+// tool results unprojected, so this proxy is the only place the wire codec runs.
+function createServer() {
+    const server = new Server({
+        name: packageJson.name,
+        version: packageJson.version,
+    }, {
+        capabilities: {
+            tools: {}
         }
     });
-    if (response.status === 200) {
-        return await response.json();
-    }
-    throw new Error('Unexpected response');
-});
-mcpServer.connect(new StdioServerTransport());
+    // tools/list is grant-filtered per principal upstream, so the advertised output
+    // schemas belong to this connection and are cached alongside it.
+    const outputSchemas = new Map();
+    server.setRequestHandler('tools/list', async (request) => {
+        const result = await forward('/mcp/tools/list', request);
+        for (const tool of result.tools) {
+            outputSchemas.set(tool.name, tool.outputSchema);
+        }
+        return result;
+    });
+    server.setRequestHandler('tools/call', async (request) => {
+        const result = await forward('/mcp/tools/call', request);
+        return server.projectCallToolResult(result, outputSchemas.get(request.params.name));
+    });
+    return server;
+}
+const handle = serveStdio(createServer);
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+        void handle.close();
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attackforge/mcp-server",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "AttackForge MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -14,17 +14,23 @@
     "build": "tsc && shx chmod +x dist/index.js",
     "clean": "rm -rf dist",
     "prepare": "npm run rebuild",
-    "rebuild": "npm run clean && npm run build"
+    "rebuild": "npm run clean && npm run build",
+    "test": "npm run build && tsc -p test && node --test test/proxy.test.ts",
+    "test:integration": "npm run build && tsc -p test && node --env-file-if-exists=.env.integration --test test/integration.test.ts"
   },
   "author": "AttackForge",
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "devDependencies": {
-    "@types/node": "^22.16.5",
+    "@modelcontextprotocol/client": "^2.1.0",
+    "@tsconfig/node22": "^22.0.6",
+    "@types/node": "^22.20.4",
     "shx": "^0.4.0",
     "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.21.0",
-    "@tsconfig/node22": "^22.0.2"
+    "@modelcontextprotocol/server": "^2.1.0"
   }
 }