@proxyflow/mcp-server 1.0.0
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.
- package/README.md +99 -0
- package/dist/index.js +92 -0
- package/package.json +38 -0
package/README.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# @proxyflow/mcp-server
|
|
2
|
+
|
|
3
|
+
让 AI 编码助手在开发新接口时,通过 MCP 自行创建/切换 mock,并等待真实请求以获取真实的 request/response 形状。
|
|
4
|
+
|
|
5
|
+
## 提供的工具
|
|
6
|
+
|
|
7
|
+
| 工具 | 说明 |
|
|
8
|
+
|------|------|
|
|
9
|
+
| `upsert_mock` | 按 URL pathname(+可选 method)创建或更新一个 mock。已存在时新增一个版本并设为激活版本,不会产生重复规则。 |
|
|
10
|
+
| `toggle_mock` | 按 URL pathname(+可选 method)开启/关闭一个已存在的 mock。找不到规则时会提示先调用 `upsert_mock`。 |
|
|
11
|
+
| `list_mocks` | 列出当前用户的所有 mock 规则(含版本列表与当前激活版本)。 |
|
|
12
|
+
| `wait_for_request` | 阻塞等待下一个匹配该 URL pathname(+可选 method)的真实请求经过代理,返回其抓包结果。适合在关闭 mock 后,触发一次真实调用来获取真实响应结构。 |
|
|
13
|
+
|
|
14
|
+
## 获取 Token
|
|
15
|
+
|
|
16
|
+
登录 proxyflow 控制台 → 设置页 → "API Tokens (MCP)" 卡片 → 生成新 Token(`pf_` 开头,仅显示一次,请立即保存)。
|
|
17
|
+
|
|
18
|
+
## 接入方式一:npx(推荐)
|
|
19
|
+
|
|
20
|
+
已发布到 npm,无需手动 clone/构建,直接在 MCP 客户端配置里用 `npx` 拉起:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"mcpServers": {
|
|
25
|
+
"proxyflow": {
|
|
26
|
+
"command": "npx",
|
|
27
|
+
"args": ["-y", "@proxyflow/mcp-server"],
|
|
28
|
+
"env": {
|
|
29
|
+
"PROXYFLOW_URL": "http://localhost:9000",
|
|
30
|
+
"PROXYFLOW_TOKEN": "pf_xxxxxxxxxxxxxxxxxxxxxxxx"
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
或使用 Claude Code CLI 添加:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
claude mcp add proxyflow \
|
|
41
|
+
--env PROXYFLOW_URL=http://localhost:9000 \
|
|
42
|
+
--env PROXYFLOW_TOKEN=pf_xxxxxxxxxxxxxxxxxxxxxxxx \
|
|
43
|
+
-- npx -y @proxyflow/mcp-server
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`npx` 会自动下载并缓存最新发布的版本,之后每次由 MCP 客户端拉起时无需重复安装。
|
|
47
|
+
|
|
48
|
+
## 接入方式二:本地构建
|
|
49
|
+
|
|
50
|
+
适合在本仓库内开发/调试这个 MCP server 本身:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cd mcp-server
|
|
54
|
+
npm install
|
|
55
|
+
npm run build
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
配置 MCP 客户端时指向本地构建产物:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"proxyflow": {
|
|
64
|
+
"command": "node",
|
|
65
|
+
"args": ["/absolute/path/to/proxyflow/mcp-server/dist/index.js"],
|
|
66
|
+
"env": {
|
|
67
|
+
"PROXYFLOW_URL": "http://localhost:9000",
|
|
68
|
+
"PROXYFLOW_TOKEN": "pf_xxxxxxxxxxxxxxxxxxxxxxxx"
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
或使用 Claude Code CLI 添加:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
claude mcp add proxyflow \
|
|
79
|
+
--env PROXYFLOW_URL=http://localhost:9000 \
|
|
80
|
+
--env PROXYFLOW_TOKEN=pf_xxxxxxxxxxxxxxxxxxxxxxxx \
|
|
81
|
+
-- node /absolute/path/to/proxyflow/mcp-server/dist/index.js
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## 环境变量
|
|
85
|
+
|
|
86
|
+
| 变量 | 必填 | 说明 |
|
|
87
|
+
|------|------|------|
|
|
88
|
+
| `PROXYFLOW_URL` | 是 | proxyflow 后端地址,例如 `http://localhost:9000` |
|
|
89
|
+
| `PROXYFLOW_TOKEN` | 是 | 在设置页生成的 API Token,`pf_` 开头 |
|
|
90
|
+
|
|
91
|
+
## 发布(维护者)
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
cd mcp-server
|
|
95
|
+
npm version <patch|minor|major>
|
|
96
|
+
npm publish --access public
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`prepublishOnly` 会在 `npm publish` 前自动执行 `npm run build`,确保 `dist/` 是最新的。
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
|
+
const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
|
|
5
|
+
const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
|
|
6
|
+
const zod_1 = require("zod");
|
|
7
|
+
const PROXYFLOW_URL = process.env.PROXYFLOW_URL;
|
|
8
|
+
const PROXYFLOW_TOKEN = process.env.PROXYFLOW_TOKEN;
|
|
9
|
+
if (!PROXYFLOW_URL || !PROXYFLOW_TOKEN) {
|
|
10
|
+
console.error('[proxyflow-mcp] Missing required environment variables.\n' +
|
|
11
|
+
' PROXYFLOW_URL — proxyflow backend URL, e.g. http://localhost:9000\n' +
|
|
12
|
+
' PROXYFLOW_TOKEN — API token generated from Settings → API Tokens (starts with "pf_")');
|
|
13
|
+
process.exit(1);
|
|
14
|
+
}
|
|
15
|
+
const baseUrl = PROXYFLOW_URL.replace(/\/+$/, '');
|
|
16
|
+
async function call(path, init) {
|
|
17
|
+
const res = await fetch(`${baseUrl}${path}`, {
|
|
18
|
+
...init,
|
|
19
|
+
headers: {
|
|
20
|
+
'Content-Type': 'application/json',
|
|
21
|
+
Authorization: `Bearer ${PROXYFLOW_TOKEN}`,
|
|
22
|
+
...(init.headers || {}),
|
|
23
|
+
},
|
|
24
|
+
});
|
|
25
|
+
let body;
|
|
26
|
+
try {
|
|
27
|
+
body = await res.json();
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
body = await res.text();
|
|
31
|
+
}
|
|
32
|
+
return { ok: res.ok, status: res.status, body };
|
|
33
|
+
}
|
|
34
|
+
function toResult(result) {
|
|
35
|
+
const text = JSON.stringify(result.body, null, 2);
|
|
36
|
+
if (!result.ok) {
|
|
37
|
+
return { isError: true, content: [{ type: 'text', text: `HTTP ${result.status}: ${text}` }] };
|
|
38
|
+
}
|
|
39
|
+
return { content: [{ type: 'text', text }] };
|
|
40
|
+
}
|
|
41
|
+
const server = new mcp_js_1.McpServer({ name: 'proxyflow-mcp', version: '1.0.0' });
|
|
42
|
+
const responseHeadersSchema = zod_1.z.record(zod_1.z.string()).optional()
|
|
43
|
+
.describe('Response headers, e.g. {"Content-Type": "application/json"}');
|
|
44
|
+
const responseBodySchema = zod_1.z.union([zod_1.z.string(), zod_1.z.record(zod_1.z.any()), zod_1.z.array(zod_1.z.any())]).optional()
|
|
45
|
+
.describe('Response body — a JSON string or a JSON value');
|
|
46
|
+
server.tool('upsert_mock', 'Create or update a mock for an API endpoint, matched by URL pathname (+ optional method). ' +
|
|
47
|
+
'If a mock already exists for the same pathname/method, adds a new version and makes it active instead of creating a duplicate rule. ' +
|
|
48
|
+
'Use this right after creating a new backend endpoint during development so the frontend/mobile client can call it against a mock immediately.', {
|
|
49
|
+
url_pattern: zod_1.z.string().describe('Full URL or path of the endpoint, e.g. "/api/users/123" or "https://api.example.com/users/123". Only the pathname is used for matching.'),
|
|
50
|
+
method: zod_1.z.string().optional().describe('HTTP method, e.g. "GET", "POST". Omit to match any method.'),
|
|
51
|
+
response_status: zod_1.z.number().int().optional().describe('HTTP status code to return. Defaults to 200.'),
|
|
52
|
+
response_body: responseBodySchema,
|
|
53
|
+
response_headers: responseHeadersSchema,
|
|
54
|
+
match_type: zod_1.z.enum(['exact', 'wildcard']).optional().describe('Defaults to "wildcard".'),
|
|
55
|
+
name: zod_1.z.string().optional().describe('Human-readable name for the mock rule/version.'),
|
|
56
|
+
delay_ms: zod_1.z.number().int().min(0).max(60000).optional().describe('Artificial response delay in milliseconds.'),
|
|
57
|
+
enabled: zod_1.z.boolean().optional().describe('Whether the mock should be active. Defaults to true.'),
|
|
58
|
+
}, async (args) => toResult(await call('/api/mocks/upsert', { method: 'POST', body: JSON.stringify(args) })));
|
|
59
|
+
server.tool('toggle_mock', 'Enable or disable an existing mock, matched by URL pathname (+ optional method). ' +
|
|
60
|
+
'Returns a 404-style error if no mock exists yet for that pathname/method — call upsert_mock first in that case.', {
|
|
61
|
+
url_pattern: zod_1.z.string().describe('Full URL or path of the endpoint. Only the pathname is used for matching.'),
|
|
62
|
+
method: zod_1.z.string().optional().describe('HTTP method. Omit to match the rule with no method restriction.'),
|
|
63
|
+
enabled: zod_1.z.boolean().describe('true to enable the mock, false to disable it (fall through to the real backend/proxy).'),
|
|
64
|
+
}, async (args) => toResult(await call('/api/rules/toggle-by-pattern', { method: 'PATCH', body: JSON.stringify(args) })));
|
|
65
|
+
server.tool('list_mocks', 'List all mock rules for the current user, including their versions and which version is active.', {
|
|
66
|
+
search: zod_1.z.string().optional().describe('Filter by rule name or URL pattern substring.'),
|
|
67
|
+
}, async ({ search }) => {
|
|
68
|
+
const qs = search ? `?search=${encodeURIComponent(search)}` : '';
|
|
69
|
+
return toResult(await call(`/api/mocks${qs}`, { method: 'GET' }));
|
|
70
|
+
});
|
|
71
|
+
server.tool('wait_for_request', 'Block until the next real HTTP request matching a URL pathname (+ optional method) passes through the proxy, then return its captured request/response. ' +
|
|
72
|
+
'Useful for discovering the real shape of a new endpoint before writing its mock — disable/skip the mock first, trigger the call from the client, and use this tool to capture what actually happened.', {
|
|
73
|
+
url_pattern: zod_1.z.string().describe('Full URL or path of the endpoint. Only the pathname is used for matching.'),
|
|
74
|
+
method: zod_1.z.string().optional().describe('HTTP method to filter on. Omit to match any method.'),
|
|
75
|
+
timeout_ms: zod_1.z.number().int().min(1000).max(60000).optional().describe('Max time to wait, in milliseconds. Defaults to 30000, clamped to [1000, 60000].'),
|
|
76
|
+
}, async ({ url_pattern, method, timeout_ms }) => {
|
|
77
|
+
const params = new URLSearchParams({ url_pattern });
|
|
78
|
+
if (method)
|
|
79
|
+
params.set('method', method);
|
|
80
|
+
if (timeout_ms)
|
|
81
|
+
params.set('timeout_ms', String(timeout_ms));
|
|
82
|
+
return toResult(await call(`/api/requests/wait?${params.toString()}`, { method: 'GET' }));
|
|
83
|
+
});
|
|
84
|
+
async function main() {
|
|
85
|
+
const transport = new stdio_js_1.StdioServerTransport();
|
|
86
|
+
await server.connect(transport);
|
|
87
|
+
console.error(`[proxyflow-mcp] connected — backend ${baseUrl}`);
|
|
88
|
+
}
|
|
89
|
+
main().catch((err) => {
|
|
90
|
+
console.error('[proxyflow-mcp] fatal error', err);
|
|
91
|
+
process.exit(1);
|
|
92
|
+
});
|
package/package.json
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@proxyflow/mcp-server",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "proxyflow MCP server — 让 AI 助手在开发新接口时自行 mock/切换/等待请求",
|
|
5
|
+
"main": "dist/index.js",
|
|
6
|
+
"publishConfig": {
|
|
7
|
+
"access": "public"
|
|
8
|
+
},
|
|
9
|
+
"bin": {
|
|
10
|
+
"proxyflow-mcp": "dist/index.js"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist"
|
|
14
|
+
],
|
|
15
|
+
"scripts": {
|
|
16
|
+
"build": "tsc",
|
|
17
|
+
"start": "node dist/index.js",
|
|
18
|
+
"prepublishOnly": "npm run build"
|
|
19
|
+
},
|
|
20
|
+
"keywords": [
|
|
21
|
+
"proxyflow",
|
|
22
|
+
"mcp",
|
|
23
|
+
"mock"
|
|
24
|
+
],
|
|
25
|
+
"author": "shibazijiang <shibazijiang@gmail.com>",
|
|
26
|
+
"license": "ISC",
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=18"
|
|
29
|
+
},
|
|
30
|
+
"dependencies": {
|
|
31
|
+
"@modelcontextprotocol/sdk": "^1.12.0",
|
|
32
|
+
"zod": "^3.23.8"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"typescript": "^5.5.4",
|
|
36
|
+
"@types/node": "^20.14.0"
|
|
37
|
+
}
|
|
38
|
+
}
|