@attackforge/mcp-server 0.2.8 → 0.3.0

package/README.md

@@ -28,6 +28,7 @@ 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
 
@@ -87,6 +88,26 @@ This MCP server implements the [Model Context Protocol](https://modelcontextprot
 
 The tools available to Claude are determined by your AttackForge instance configuration.
 
+### 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 host.
+
+### Errors
+
+Failures reported by 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 |
+
 ## Development
 
 ```bash

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.8",
+  "version": "0.3.0",
   "description": "AttackForge MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -18,13 +18,16 @@
   },
   "author": "AttackForge",
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "devDependencies": {
+    "@tsconfig/node22": "^22.0.2",
     "@types/node": "^22.16.5",
     "shx": "^0.4.0",
     "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.21.0",
-    "@tsconfig/node22": "^22.0.2"
+    "@modelcontextprotocol/server": "^2.0.0"
   }
 }