@attackforge/mcp-server 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +32 -34
  2. package/package.json +8 -5
package/README.md CHANGED
@@ -1,24 +1,13 @@
1
1
  # AttackForge MCP Server
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ## Installation
6
6
 
7
- ### From npm
8
-
9
7
  ```bash
10
8
  npm install -g @attackforge/mcp-server
11
9
  ```
12
10
 
13
- ### From source
14
-
15
- ```bash
16
- git clone https://github.com/AttackForge/af-mcp-server.git
17
- cd af-mcp-server
18
- npm install
19
- npm run build
20
- ```
21
-
22
11
  ## Configuration
23
12
 
24
13
  The server requires the following environment variables:
@@ -32,12 +21,14 @@ The server requires the following environment variables:
32
21
 
33
22
  ## Usage
34
23
 
24
+ 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.
25
+
35
26
  ### Claude Desktop
36
27
 
37
28
  Add to your Claude Desktop configuration file:
38
29
 
39
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
40
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
30
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
31
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
41
32
 
42
33
  ```json
43
34
  {
@@ -55,20 +46,8 @@ Add to your Claude Desktop configuration file:
55
46
 
56
47
  ### Claude Code
57
48
 
58
- Add to your Claude Code settings:
59
-
60
- ```json
61
- {
62
- "mcpServers": {
63
- "attackforge": {
64
- "command": "af-mcp-server",
65
- "env": {
66
- "AF_HOSTNAME": "your-instance.attackforge.com",
67
- "AF_USER_KEY": "your-api-key"
68
- }
69
- }
70
- }
71
- }
49
+ ```bash
50
+ claude mcp add attackforge -e AF_HOSTNAME=your-instance.attackforge.com -e AF_USER_KEY=your-api-key -- af-mcp-server
72
51
  ```
73
52
 
74
53
  ### Running directly
@@ -77,16 +56,18 @@ Add to your Claude Code settings:
77
56
  AF_HOSTNAME=your-instance.attackforge.com AF_USER_KEY=your-api-key af-mcp-server
78
57
  ```
79
58
 
59
+ The server then waits for an MCP client on stdin and stdout; this is mainly useful for checking the configuration starts cleanly.
60
+
80
61
  ## How It Works
81
62
 
82
63
  This MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io/) and proxies requests to your AttackForge instance:
83
64
 
84
- 1. Claude connects to the server via stdio transport
85
- 2. When Claude lists available tools, the server fetches them from `https://{AF_HOSTNAME}/mcp/tools/list`
86
- 3. When Claude calls a tool, the server forwards the request to `https://{AF_HOSTNAME}/mcp/tools/call`
65
+ 1. The MCP client starts the server and connects to it over stdio
66
+ 2. When the client lists available tools, the server fetches them from `https://{AF_HOSTNAME}/mcp/tools/list`
67
+ 3. When the client calls a tool, the server forwards the request to `https://{AF_HOSTNAME}/mcp/tools/call`
87
68
  4. All requests are authenticated using the `x-user-key` header
88
69
 
89
- The tools available to Claude are determined by your AttackForge instance configuration.
70
+ The tools available are determined by your AttackForge instance configuration and the permissions of the user whose key is configured.
90
71
 
91
72
  ### Protocol versions
92
73
 
@@ -95,11 +76,11 @@ The server is built on the v2 MCP TypeScript SDK (`@modelcontextprotocol/server`
95
76
  - **Modern** — the `2026-07-28` revision, negotiated with `server/discover`
96
77
  - **Legacy** — the `2024-10-07` through `2025-11-25` revisions, negotiated with the `initialize` handshake
97
78
 
98
- 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.
79
+ 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.
99
80
 
100
81
  ### Errors
101
82
 
102
- Failures reported by AttackForge are relayed as MCP protocol errors naming the actual cause:
83
+ Failures reaching AttackForge are relayed as MCP protocol errors naming the actual cause:
103
84
 
104
85
  | Status | Meaning |
105
86
  |--------|---------|
@@ -107,6 +88,9 @@ Failures reported by AttackForge are relayed as MCP protocol errors naming the a
107
88
  | `401` | `AF_USER_KEY` is not a valid AttackForge API key |
108
89
  | `404` | Local MCP access is disabled on the instance, or the user has no access to the MCP module |
109
90
  | other | Relayed with the status and response body |
91
+ | none | AttackForge could not be reached, or did not respond within `AF_TIMEOUT_MS` |
92
+
93
+ 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.
110
94
 
111
95
  ## Development
112
96
 
@@ -124,6 +108,20 @@ npm run clean
124
108
  npm run rebuild
125
109
  ```
126
110
 
111
+ ### Testing
112
+
113
+ ```bash
114
+ # Contract tests: the built server against a mock AttackForge, on both protocol eras
115
+ npm test
116
+
117
+ # Integration tests against a real AttackForge instance
118
+ npm run test:integration
119
+ ```
120
+
121
+ The tests are TypeScript run directly by Node, which needs Node.js 22.18 or later.
122
+
123
+ 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.
124
+
127
125
  ## Requirements
128
126
 
129
127
  - Node.js 22 or later
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attackforge/mcp-server",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "AttackForge MCP Server",
5
5
  "main": "dist/index.js",
6
6
  "type": "module",
@@ -14,7 +14,9 @@
14
14
  "build": "tsc && shx chmod +x dist/index.js",
15
15
  "clean": "rm -rf dist",
16
16
  "prepare": "npm run rebuild",
17
- "rebuild": "npm run clean && npm run build"
17
+ "rebuild": "npm run clean && npm run build",
18
+ "test": "npm run build && tsc -p test && node --test test/proxy.test.ts",
19
+ "test:integration": "npm run build && tsc -p test && node --env-file-if-exists=.env.integration --test test/integration.test.ts"
18
20
  },
19
21
  "author": "AttackForge",
20
22
  "license": "MIT",
@@ -22,12 +24,13 @@
22
24
  "node": ">=22"
23
25
  },
24
26
  "devDependencies": {
25
- "@tsconfig/node22": "^22.0.2",
26
- "@types/node": "^22.16.5",
27
+ "@modelcontextprotocol/client": "^2.1.0",
28
+ "@tsconfig/node22": "^22.0.6",
29
+ "@types/node": "^22.20.4",
27
30
  "shx": "^0.4.0",
28
31
  "typescript": "^6.0.2"
29
32
  },
30
33
  "dependencies": {
31
- "@modelcontextprotocol/server": "^2.0.0"
34
+ "@modelcontextprotocol/server": "^2.1.0"
32
35
  }
33
36
  }