merge: candidate jev-mcp-integration into local_dev
This commit is contained in:
weichen
@@ -3,6 +3,10 @@
|
||||
"agentctl": {
|
||||
"command": "node",
|
||||
"args": ["${workspaceFolder}/scripts/mcp/agentctl-mcp.mjs"]
|
||||
},
|
||||
"jev": {
|
||||
"command": "node",
|
||||
"args": ["${workspaceFolder}/scripts/mcp/jev-mcp.mjs"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: jev-decide
|
||||
description: Use jev-service typed decisions (choice/noul/numeric with probabilities) for Agent-System governance classification. Use when choosing task tier, validation level, reject-code routing, or other closed-enum judgments.
|
||||
---
|
||||
|
||||
# jev-decide（治理决策）
|
||||
|
||||
依赖 MCP 服务器 `jev`（[`scripts/mcp/jev-mcp.mjs`](../../../scripts/mcp/jev-mcp.mjs)）。凭证在本机 `~/.secrets/jev/`（`api.key`、`base-url`），**禁止**写入仓库、commit 或聊天。
|
||||
|
||||
## 何时用
|
||||
|
||||
输入是情境文本、输出是**封闭枚举 / yes-no / 分桶数值**时调用 `jev_decide`，例如：
|
||||
|
||||
| 决策点 | 建议 questions |
|
||||
|---|---|
|
||||
| 任务分级（是否开 worktree） | `choice`：`info_reply` / `single_task` / `cross_module` |
|
||||
| 验证层级（验证契约） | `choice`（可多题）：`doc` / `script` / `go` / `frontend` / `migration` / `product_pi` |
|
||||
| 拒绝码处置 | `choice`：`reconcile` / `re_snapshot` / `fix_record_id` / `request_capability` / `abort` |
|
||||
| 是否 blocker / 是否触碰重验面 | `noul` |
|
||||
|
||||
不适合：需要解释链、多步规划、自由文本生成——那些走大模型或 agentctl 确定性门禁。
|
||||
|
||||
## 调用约定
|
||||
|
||||
1. 可选先 `jev_health`；失败则本机判断，勿阻塞写路径。
|
||||
2. `jev_decide`：同一情境的多问合成一次请求。
|
||||
3. 问句**正向措辞**，避免双重否定。
|
||||
4. 置信度路由：
|
||||
- `confidence >= 0.9` 且 top1−top2 ≥ 0.15 → 可采用
|
||||
- 否则 → agent 自行按规范裁定，把 jev 结果当参考
|
||||
5. 401/超时/`answers.*.error` → 降级到本机判断；勿把决策失败变成业务失败。
|
||||
|
||||
## 示例（任务分级）
|
||||
|
||||
```json
|
||||
{
|
||||
"context": "用户请求：给 CURRENT 加一行认领说明，不改代码",
|
||||
"questions": {
|
||||
"tier": {
|
||||
"type": "choice",
|
||||
"question": "This request matches which AGENTS task tier?",
|
||||
"options": ["info_reply", "single_task", "cross_module"]
|
||||
},
|
||||
"needs_worktree": {
|
||||
"type": "noul",
|
||||
"question": "Does this require a new feature/fix worktree?"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
权威矩阵仍以 [AGENTS.md](../../../AGENTS.md)、[验证契约](../../../.doc/ops/2026-09-21-validation-contract.md) 为准；jev 只加速封闭枚举分类，不替代机器门禁（admit/hooks/docs apply）。
|
||||
@@ -18,6 +18,7 @@
|
||||
|
||||
| owner | task | branch | worktree | mutex | status |
|
||||
|---|---|---|---|---|---|
|
||||
| Cursor | jev-mcp-integration-2026-09-24 | feature/jev-mcp-integration-2026-09-24 | .worktrees/jev-mcp-integration-2026-09-24 | jev-mcp+docs | in_progress |
|
||||
| Cursor | integrate-intent-plan-u9u12-land-2026-09-24 | feature/integrate-intent-plan-u9u12-land-2026-09-24 | .worktrees/integrate-intent-plan-u9u12-land-2026-09-24 | git:dev | done |
|
||||
| Cursor | integrate-pi-narrative-docs-2026-09-23 | feature/integrate-pi-narrative-docs-2026-09-23 | .worktrees/integrate-pi-narrative-final-closeout-b-2026-09-23 | git:dev | done |
|
||||
| Cursor | pi-narrative-final-closeout-b-2026-09-23 | feature/pi-narrative-final-closeout-b-2026-09-23 | .worktrees/pi-narrative-final-closeout-2026-09-23 | docgov | done |
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
status: in_progress
|
||||
write_scope: scripts/mcp,.cursor,.doc/ops/short-term,.doc/test-reports
|
||||
mutex: jev-mcp+docs
|
||||
base_dev_sha: b6f21e8a947c4bb8ab1171e05f7404b35f7bd2f1
|
||||
review_state: pending
|
||||
integration_state: pending
|
||||
deployment: not_required
|
||||
cleanup: pending
|
||||
remote_sync: not_pushed
|
||||
owner: Cursor
|
||||
task_id: jev-mcp-integration-2026-09-24
|
||||
---
|
||||
|
||||
# jev-service 治理侧 MCP 接入
|
||||
|
||||
## 目标
|
||||
|
||||
将本机 jev-service（类型化 decision API）以独立 MCP 服务器 `jev` 接入本仓库治理链路，供 agent 在封闭枚举决策点调用；凭证仅存 `~/.secrets/jev/`，不进 git。
|
||||
|
||||
## 交付物
|
||||
|
||||
- `scripts/mcp/jev-mcp.mjs` — `jev_decide` / `jev_health`
|
||||
- `.cursor/mcp.json` — 注册 `jev` server
|
||||
- `.cursor/skills/jev-decide/SKILL.md` — 治理用例指引
|
||||
- `.doc/test-reports/2026-09-24-jev-mcp-integration-test-report.md` — 真实链路证据
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不改 Go 产品路径（intent / coordinator / pi-agent）
|
||||
- 不 push、不晋升 test/main
|
||||
- 不把 API key / 完整 secret 写入仓库或报告正文
|
||||
|
||||
## 验证计划
|
||||
|
||||
1. MCP initialize + tools/list（stdio NDJSON 或 Content-Length）
|
||||
2. `jev_health` 对本机与 frp 备用 URL
|
||||
3. `jev_decide` 治理样例（任务分级 + 验证层级）
|
||||
4. 401 负例（错误 key）
|
||||
5. 产品 PI 全链路：NOT REQUIRED（工程 MCP/文档变更，依据 PROJECT.md §验证入口与 test-reports-standard 例外）
|
||||
@@ -0,0 +1,74 @@
|
||||
# jev-service 治理侧 MCP 集成 测试报告
|
||||
|
||||
## 一、 测试背景 (Background)
|
||||
|
||||
将本机 jev-service（类型化 `/v1/decide`）以独立 MCP 服务器接入 Agent-System 治理链路，供 agent 在任务分级、验证层级等封闭枚举决策点调用。凭证仅存本机 `~/.secrets/jev/`，不进入仓库。
|
||||
|
||||
## 二、 测试目标 (Test Objectives)
|
||||
|
||||
- MCP stdio 握手（initialize / tools/list）成功
|
||||
- `jev_health` / `jev_decide` 对本机 `http://127.0.0.1:8767` 真实可用
|
||||
- 错误 API key 返回 401 且 MCP `isError=true`
|
||||
- frp 备用 URL 可真实 decide
|
||||
- 资产目录无 API key 明文泄漏
|
||||
- 产品 PI 全链路：NOT REQUIRED（工程 MCP/文档变更；依据 PROJECT.md 验证入口与 test-reports-standard 纯工程例外）
|
||||
|
||||
## 三、 测试方案与环境 (Test Plan & Environment)
|
||||
|
||||
- OS：Linux；Node：v26.9.0
|
||||
- jev-service：本机 :8767 + frp `https://fun.u1680832.nyat.app:34608`（healthz 均 ok）
|
||||
- 被测：`.worktrees/jev-mcp-integration-2026-09-24/scripts/mcp/jev-mcp.mjs`
|
||||
- 层级：MCP 协议冒烟 + HTTP 端到端；无 Go/前端回归要求
|
||||
- 证据：`.doc/test-reports/assets/2026-09-24-jev-mcp-integration/`
|
||||
|
||||
## 四、 预期结果 (Expected Results)
|
||||
|
||||
| 用例 | 预期 |
|
||||
|---|---|
|
||||
| initialize | serverInfo.name=`jev` |
|
||||
| tools/list | 含 `jev_health`、`jev_decide` |
|
||||
| decide（文档小改） | tier≈single_task；validation≈doc；低风险 |
|
||||
| 401 | isError + unauthorized 文案，不崩溃 |
|
||||
| frp decide | HTTP 成功返回 answers |
|
||||
|
||||
## 五、 实际测试结果与判定 (Actual Results & Evaluation)
|
||||
|
||||
### 用例 1：MCP 握手 + 本地 decide
|
||||
|
||||
- **测试输入 (Input)**：NDJSON initialize → tools/list → jev_health → jev_decide（任务分级+验证层级+是否开 worktree）
|
||||
- **实际输出 (Actual Output)**：见 `assets/2026-09-24-jev-mcp-integration/01-local-handshake-decide.decoded.json`
|
||||
- health：`ok=true`，base_url=`http://127.0.0.1:8767`
|
||||
- answers：`tier=single_task` confidence≈0.909；`validation=doc` confidence≈0.996；`needs_worktree=no` confidence≈0.917
|
||||
- **评价判定 (Evaluation / Verdict)**：PASS
|
||||
- **性能与耗时 (Duration & Latency)**：整批 MCP 往返约 2.2s（含 3 问 decide）
|
||||
|
||||
### 用例 2：401 负例
|
||||
|
||||
- **测试输入 (Input)**：`JEV_API_KEY=definitely-wrong-key` + jev_decide
|
||||
- **实际输出 (Actual Output)**：`isError=true`，文案 `jev_decide unauthorized (401): check ~/.secrets/jev/api.key or JEV_API_KEY`（`02-auth-401.decoded.json`）
|
||||
- **评价判定**：PASS
|
||||
- **性能与耗时**：约 3s 内返回
|
||||
|
||||
### 用例 3：frp 远程 decide
|
||||
|
||||
- **测试输入 (Input)**：`base_url=https://fun.u1680832.nyat.app:34608`，validation 六类选择
|
||||
- **实际输出 (Actual Output)**：`validation=script` confidence≈0.668（`03-frp-decide.decoded.json`）——本批改动含 MCP 脚本，script 合理；置信中等，技能约定应回退 agent 自判
|
||||
- **评价判定**：PASS（连通与契约正确；中置信按设计不强制采纳）
|
||||
- **性能与耗时**：约 3s 内完成
|
||||
|
||||
### 用例 4：探活延迟与密钥泄漏扫描
|
||||
|
||||
- **实际输出**：`04-latency.txt` — local healthz ≈2ms；frp ≈49ms；`grep` 资产目录无 key 明文
|
||||
- **评价判定**：PASS
|
||||
|
||||
## 六、 自动化测试套件汇总 (Test Suite Execution)
|
||||
|
||||
- `go test ./...`：NOT REQUIRED（未改 Go；工程 MCP/文档）
|
||||
- 产品 PI Runner：NOT REQUIRED（同上）
|
||||
- 本轮执行：MCP NDJSON 真实调用 4 组 + curl healthz 双端点
|
||||
|
||||
## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
|
||||
|
||||
- 治理侧 MCP 接入达到合入标准：握手、鉴权、本地/frp decide、错误路径均有真实证据。
|
||||
- 合入后需在 Cursor 重载 MCP 以加载 `jev` server。
|
||||
- 后续（另授权）：产品侧 shadow 评测与低风险决策点灰度，不在本任务范围。
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
[
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"protocolVersion": "2024-11-05",
|
||||
"capabilities": {
|
||||
"tools": {}
|
||||
},
|
||||
"serverInfo": {
|
||||
"name": "jev",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"result": {
|
||||
"tools": [
|
||||
{
|
||||
"name": "jev_health",
|
||||
"description": "Probe jev-service /healthz (no auth). Returns ok/model/llama_server status. Use before decide when unsure the service is up.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"base_url": {
|
||||
"type": "string",
|
||||
"description": "Optional override; default JEV_BASE_URL or ~/.secrets/jev/base-url or http://127.0.0.1:8767"
|
||||
},
|
||||
"timeout_ms": {
|
||||
"type": "number",
|
||||
"description": "Request timeout ms (default 15000)"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "jev_decide",
|
||||
"description": "Call jev-service POST /v1/decide: typed choice/noul/numeric answers with real probability distributions. For governance decisions (task tier, validation level, reject routing). Low confidence (top1-top2 < 0.15) → fall back to agent judgment. Requires API key from ~/.secrets/jev/api.key or JEV_API_KEY.",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"context": {
|
||||
"type": "string",
|
||||
"description": "Situation text (user request, change summary, error code context, …)"
|
||||
},
|
||||
"questions": {
|
||||
"type": "object",
|
||||
"description": "Map of answer name → {type: choice|noul|numeric, question, options?, min?, max?}. Example: {\"tier\":{\"type\":\"choice\",\"question\":\"Task tier?\",\"options\":[\"info_reply\",\"single_task\",\"cross_module\"]}}",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"base_url": {
|
||||
"type": "string",
|
||||
"description": "Optional URL override"
|
||||
},
|
||||
"timeout_ms": {
|
||||
"type": "number",
|
||||
"description": "Request timeout ms (default 15000)"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"context",
|
||||
"questions"
|
||||
],
|
||||
"additionalProperties": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 3,
|
||||
"result": {
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "{\n \"base_url\": \"http://127.0.0.1:8767\",\n \"ok\": true,\n \"model\": \"jev-clone-qwen3-4b/0.2.0\",\n \"llama_server\": {\n \"status\": \"ok\"\n },\n \"auth\": true\n}"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 4,
|
||||
"result": {
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "{\n \"base_url\": \"http://127.0.0.1:8767\",\n \"model\": \"jev-clone-qwen3-4b/0.2.0\",\n \"answers\": {\n \"tier\": {\n \"type\": \"choice\",\n \"choice\": \"single_task\",\n \"confidence\": 0.909262,\n \"probabilities\": {\n \"info_reply\": 0.05180025,\n \"single_task\": 0.90926193,\n \"cross_module\": 0.03893782\n }\n },\n \"validation\": {\n \"type\": \"choice\",\n \"choice\": \"doc\",\n \"confidence\": 0.995727,\n \"probabilities\": {\n \"doc\": 0.995727,\n \"script\": 0.00013765,\n \"go\": 0.00012722,\n \"frontend\": 0.00175551,\n \"migration\": 0.00068579,\n \"product_pi\": 0.00156682\n }\n },\n \"needs_worktree\": {\n \"type\": \"noul\",\n \"choice\": \"no\",\n \"confidence\": 0.917266,\n \"probabilities\": {\n \"yes\": 0.08273366,\n \"no\": 0.91726634\n },\n \"noul\": 0,\n \"yes\": false\n }\n }\n}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
+9
@@ -0,0 +1,9 @@
|
||||
Content-Length: 140
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"jev","version":"1.0.0"}}}Content-Length: 1511
|
||||
|
||||
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"jev_health","description":"Probe jev-service /healthz (no auth). Returns ok/model/llama_server status. Use before decide when unsure the service is up.","inputSchema":{"type":"object","properties":{"base_url":{"type":"string","description":"Optional override; default JEV_BASE_URL or ~/.secrets/jev/base-url or http://127.0.0.1:8767"},"timeout_ms":{"type":"number","description":"Request timeout ms (default 15000)"}},"additionalProperties":false}},{"name":"jev_decide","description":"Call jev-service POST /v1/decide: typed choice/noul/numeric answers with real probability distributions. For governance decisions (task tier, validation level, reject routing). Low confidence (top1-top2 < 0.15) → fall back to agent judgment. Requires API key from ~/.secrets/jev/api.key or JEV_API_KEY.","inputSchema":{"type":"object","properties":{"context":{"type":"string","description":"Situation text (user request, change summary, error code context, …)"},"questions":{"type":"object","description":"Map of answer name → {type: choice|noul|numeric, question, options?, min?, max?}. Example: {\"tier\":{\"type\":\"choice\",\"question\":\"Task tier?\",\"options\":[\"info_reply\",\"single_task\",\"cross_module\"]}}","additionalProperties":true},"base_url":{"type":"string","description":"Optional URL override"},"timeout_ms":{"type":"number","description":"Request timeout ms (default 15000)"}},"required":["context","questions"],"additionalProperties":false}}]}}Content-Length: 253
|
||||
|
||||
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\n \"base_url\": \"http://127.0.0.1:8767\",\n \"ok\": true,\n \"model\": \"jev-clone-qwen3-4b/0.2.0\",\n \"llama_server\": {\n \"status\": \"ok\"\n },\n \"auth\": true\n}"}]}}Content-Length: 1075
|
||||
|
||||
{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"{\n \"base_url\": \"http://127.0.0.1:8767\",\n \"model\": \"jev-clone-qwen3-4b/0.2.0\",\n \"answers\": {\n \"tier\": {\n \"type\": \"choice\",\n \"choice\": \"single_task\",\n \"confidence\": 0.909262,\n \"probabilities\": {\n \"info_reply\": 0.05180025,\n \"single_task\": 0.90926193,\n \"cross_module\": 0.03893782\n }\n },\n \"validation\": {\n \"type\": \"choice\",\n \"choice\": \"doc\",\n \"confidence\": 0.995727,\n \"probabilities\": {\n \"doc\": 0.995727,\n \"script\": 0.00013765,\n \"go\": 0.00012722,\n \"frontend\": 0.00175551,\n \"migration\": 0.00068579,\n \"product_pi\": 0.00156682\n }\n },\n \"needs_worktree\": {\n \"type\": \"noul\",\n \"choice\": \"no\",\n \"confidence\": 0.917266,\n \"probabilities\": {\n \"yes\": 0.08273366,\n \"no\": 0.91726634\n },\n \"noul\": 0,\n \"yes\": false\n }\n }\n}"}]}}
|
||||
@@ -0,0 +1,29 @@
|
||||
[
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"protocolVersion": "2024-11-05",
|
||||
"capabilities": {
|
||||
"tools": {}
|
||||
},
|
||||
"serverInfo": {
|
||||
"name": "jev",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"result": {
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "jev_decide unauthorized (401): check ~/.secrets/jev/api.key or JEV_API_KEY"
|
||||
}
|
||||
],
|
||||
"isError": true
|
||||
}
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,5 @@
|
||||
Content-Length: 140
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"jev","version":"1.0.0"}}}Content-Length: 162
|
||||
|
||||
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"jev_decide unauthorized (401): check ~/.secrets/jev/api.key or JEV_API_KEY"}],"isError":true}}
|
||||
@@ -0,0 +1,28 @@
|
||||
[
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"protocolVersion": "2024-11-05",
|
||||
"capabilities": {
|
||||
"tools": {}
|
||||
},
|
||||
"serverInfo": {
|
||||
"name": "jev",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"result": {
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "{\n \"base_url\": \"https://fun.u1680832.nyat.app:34608\",\n \"model\": \"jev-clone-qwen3-4b/0.2.0\",\n \"answers\": {\n \"validation\": {\n \"type\": \"choice\",\n \"choice\": \"script\",\n \"confidence\": 0.668127,\n \"probabilities\": {\n \"doc\": 0.0784743,\n \"script\": 0.6681266,\n \"go\": 0.13105554,\n \"frontend\": 0.01885709,\n \"migration\": 0.05828189,\n \"product_pi\": 0.04520459\n }\n }\n }\n}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,5 @@
|
||||
Content-Length: 140
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"jev","version":"1.0.0"}}}Content-Length: 559
|
||||
|
||||
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\n \"base_url\": \"https://fun.u1680832.nyat.app:34608\",\n \"model\": \"jev-clone-qwen3-4b/0.2.0\",\n \"answers\": {\n \"validation\": {\n \"type\": \"choice\",\n \"choice\": \"script\",\n \"confidence\": 0.668127,\n \"probabilities\": {\n \"doc\": 0.0784743,\n \"script\": 0.6681266,\n \"go\": 0.13105554,\n \"frontend\": 0.01885709,\n \"migration\": 0.05828189,\n \"product_pi\": 0.04520459\n }\n }\n }\n}"}]}}
|
||||
@@ -0,0 +1,4 @@
|
||||
local_healthz:
|
||||
{"ok": true, "model": "jev-clone-qwen3-4b/0.2.0", "llama_server": {"status": "ok"}, "auth": true} http=200 time=0.001998
|
||||
frp_healthz:
|
||||
{"ok": true, "model": "jev-clone-qwen3-4b/0.2.0", "llama_server": {"status": "ok"}, "auth": true} http=200 time=0.048645
|
||||
+15
-4
@@ -1,12 +1,23 @@
|
||||
# agentctl MCP (stdio)
|
||||
# MCP servers (stdio)
|
||||
|
||||
Zero-dependency Node MCP server wrapping `scripts/agentctl.py`.
|
||||
Zero-dependency Node MCP wrappers used by Cursor (see [`.cursor/mcp.json`](../../.cursor/mcp.json)).
|
||||
|
||||
| Server | Script | Purpose |
|
||||
|---|---|---|
|
||||
| `agentctl` | `agentctl-mcp.mjs` | Lease / docs apply / validate / queue |
|
||||
| `jev` | `jev-mcp.mjs` | Typed decide/health against local or remote jev-service |
|
||||
|
||||
```bash
|
||||
# from repo root
|
||||
node scripts/mcp/agentctl-mcp.mjs
|
||||
node scripts/mcp/jev-mcp.mjs
|
||||
```
|
||||
|
||||
Cursor loads it via [`.cursor/mcp.json`](../../.cursor/mcp.json). Reload MCP after checkout.
|
||||
## jev credentials (not in git)
|
||||
|
||||
`lease_run` / `validate` take `command` as an argv array (no shell). Set `AGENTCTL_REPO` only when the script is not under the repo tree.
|
||||
- `~/.secrets/jev/api.key` (chmod 600) or env `JEV_API_KEY`
|
||||
- `~/.secrets/jev/base-url` or env `JEV_BASE_URL` (default `http://127.0.0.1:8767`)
|
||||
|
||||
Reload MCP after checkout. See skill `.cursor/skills/jev-decide/SKILL.md`.
|
||||
|
||||
`lease_run` / `validate` take `command` as an argv array (no shell). Set `AGENTCTL_REPO` only when the agentctl script is not under the repo tree.
|
||||
|
||||
Executable
+250
@@ -0,0 +1,250 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* jev-service MCP (stdio, zero deps). Typed decide/health against local or frp jev-server.
|
||||
* Credentials: ~/.secrets/jev/api.key and ~/.secrets/jev/base-url (or JEV_API_KEY / JEV_BASE_URL).
|
||||
* Never embeds secrets in this file or logs.
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
|
||||
const DEFAULT_BASE = 'http://127.0.0.1:8767';
|
||||
const DEFAULT_TIMEOUT_MS = 15000;
|
||||
const SECRETS_DIR = path.join(os.homedir(), '.secrets', 'jev');
|
||||
|
||||
function readSecretFile(name) {
|
||||
const p = path.join(SECRETS_DIR, name);
|
||||
try {
|
||||
if (!fs.existsSync(p)) return null;
|
||||
return fs.readFileSync(p, 'utf8').trim() || null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function resolveBaseUrl() {
|
||||
return (process.env.JEV_BASE_URL || readSecretFile('base-url') || DEFAULT_BASE).replace(/\/$/, '');
|
||||
}
|
||||
|
||||
function resolveApiKey() {
|
||||
return process.env.JEV_API_KEY || readSecretFile('api.key') || null;
|
||||
}
|
||||
|
||||
function textResult(payload) {
|
||||
const body = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
|
||||
return { content: [{ type: 'text', text: body }] };
|
||||
}
|
||||
|
||||
function errResult(msg) {
|
||||
return { content: [{ type: 'text', text: msg }], isError: true };
|
||||
}
|
||||
|
||||
const TOOLS = [
|
||||
{
|
||||
name: 'jev_health',
|
||||
description:
|
||||
'Probe jev-service /healthz (no auth). Returns ok/model/llama_server status. Use before decide when unsure the service is up.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
base_url: {
|
||||
type: 'string',
|
||||
description: 'Optional override; default JEV_BASE_URL or ~/.secrets/jev/base-url or http://127.0.0.1:8767',
|
||||
},
|
||||
timeout_ms: { type: 'number', description: 'Request timeout ms (default 15000)' },
|
||||
},
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'jev_decide',
|
||||
description:
|
||||
'Call jev-service POST /v1/decide: typed choice/noul/numeric answers with real probability distributions. For governance decisions (task tier, validation level, reject routing). Low confidence (top1-top2 < 0.15) → fall back to agent judgment. Requires API key from ~/.secrets/jev/api.key or JEV_API_KEY.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
context: {
|
||||
type: 'string',
|
||||
description: 'Situation text (user request, change summary, error code context, …)',
|
||||
},
|
||||
questions: {
|
||||
type: 'object',
|
||||
description:
|
||||
'Map of answer name → {type: choice|noul|numeric, question, options?, min?, max?}. Example: {"tier":{"type":"choice","question":"Task tier?","options":["info_reply","single_task","cross_module"]}}',
|
||||
additionalProperties: true,
|
||||
},
|
||||
base_url: { type: 'string', description: 'Optional URL override' },
|
||||
timeout_ms: { type: 'number', description: 'Request timeout ms (default 15000)' },
|
||||
},
|
||||
required: ['context', 'questions'],
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
];
|
||||
|
||||
async function httpJson(url, { method = 'GET', headers = {}, body, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
|
||||
const ctrl = new AbortController();
|
||||
const timer = setTimeout(() => ctrl.abort(), timeoutMs);
|
||||
try {
|
||||
const res = await fetch(url, {
|
||||
method,
|
||||
headers,
|
||||
body,
|
||||
signal: ctrl.signal,
|
||||
});
|
||||
const text = await res.text();
|
||||
let json = null;
|
||||
try {
|
||||
json = text ? JSON.parse(text) : null;
|
||||
} catch {
|
||||
json = { raw: text };
|
||||
}
|
||||
return { status: res.status, ok: res.ok, json, text };
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
|
||||
async function callTool(name, args = {}) {
|
||||
const base = (args.base_url || resolveBaseUrl()).replace(/\/$/, '');
|
||||
const timeoutMs = Number(args.timeout_ms) > 0 ? Number(args.timeout_ms) : DEFAULT_TIMEOUT_MS;
|
||||
|
||||
switch (name) {
|
||||
case 'jev_health': {
|
||||
try {
|
||||
const r = await httpJson(`${base}/healthz`, { timeoutMs });
|
||||
if (!r.ok) {
|
||||
return errResult(`jev_health HTTP ${r.status}: ${r.text.slice(0, 500)}`);
|
||||
}
|
||||
return textResult({ base_url: base, ...r.json });
|
||||
} catch (e) {
|
||||
return errResult(`jev_health failed: ${e?.name === 'AbortError' ? 'timeout' : String(e?.message || e)}`);
|
||||
}
|
||||
}
|
||||
case 'jev_decide': {
|
||||
if (!args.context || typeof args.context !== 'string') {
|
||||
return errResult('jev_decide.context must be a non-empty string');
|
||||
}
|
||||
if (!args.questions || typeof args.questions !== 'object' || Array.isArray(args.questions)) {
|
||||
return errResult('jev_decide.questions must be an object map');
|
||||
}
|
||||
const key = resolveApiKey();
|
||||
if (!key) {
|
||||
return errResult(
|
||||
'jev API key missing: set JEV_API_KEY or create ~/.secrets/jev/api.key (chmod 600). Do not put the key in chat/repo.',
|
||||
);
|
||||
}
|
||||
try {
|
||||
const r = await httpJson(`${base}/v1/decide`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
Authorization: `Bearer ${key}`,
|
||||
},
|
||||
body: JSON.stringify({ context: args.context, questions: args.questions }),
|
||||
timeoutMs,
|
||||
});
|
||||
if (r.status === 401) {
|
||||
return errResult('jev_decide unauthorized (401): check ~/.secrets/jev/api.key or JEV_API_KEY');
|
||||
}
|
||||
if (!r.ok) {
|
||||
return errResult(`jev_decide HTTP ${r.status}: ${r.text.slice(0, 800)}`);
|
||||
}
|
||||
return textResult({
|
||||
base_url: base,
|
||||
model: r.json?.model,
|
||||
answers: r.json?.answers,
|
||||
});
|
||||
} catch (e) {
|
||||
return errResult(`jev_decide failed: ${e?.name === 'AbortError' ? 'timeout' : String(e?.message || e)}`);
|
||||
}
|
||||
}
|
||||
default:
|
||||
return errResult(`unknown tool: ${name}`);
|
||||
}
|
||||
}
|
||||
|
||||
function send(msg) {
|
||||
const body = JSON.stringify(msg);
|
||||
process.stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`);
|
||||
}
|
||||
|
||||
function handle(msg) {
|
||||
if (!msg || typeof msg !== 'object') return;
|
||||
if (msg.method && msg.id === undefined) {
|
||||
return;
|
||||
}
|
||||
const { id, method, params } = msg;
|
||||
const reply = (result) => send({ jsonrpc: '2.0', id, result });
|
||||
const fail = (code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
|
||||
|
||||
try {
|
||||
if (method === 'initialize') {
|
||||
reply({
|
||||
protocolVersion: params?.protocolVersion || '2024-11-05',
|
||||
capabilities: { tools: {} },
|
||||
serverInfo: { name: 'jev', version: '1.0.0' },
|
||||
});
|
||||
return;
|
||||
}
|
||||
if (method === 'tools/list') {
|
||||
reply({ tools: TOOLS });
|
||||
return;
|
||||
}
|
||||
if (method === 'tools/call') {
|
||||
const name = params?.name;
|
||||
const args = params?.arguments || {};
|
||||
Promise.resolve(callTool(name, args))
|
||||
.then((result) => reply(result))
|
||||
.catch((e) => fail(-32000, String(e?.stack || e)));
|
||||
return;
|
||||
}
|
||||
if (method === 'ping') {
|
||||
reply({});
|
||||
return;
|
||||
}
|
||||
fail(-32601, `Method not found: ${method}`);
|
||||
} catch (e) {
|
||||
fail(-32000, String(e?.stack || e));
|
||||
}
|
||||
}
|
||||
|
||||
// Support both Content-Length framed MCP and newline-delimited JSON (for tests).
|
||||
let buf = Buffer.alloc(0);
|
||||
process.stdin.on('data', (chunk) => {
|
||||
buf = Buffer.concat([buf, chunk]);
|
||||
while (true) {
|
||||
const headerEnd = buf.indexOf('\r\n\r\n');
|
||||
if (headerEnd !== -1) {
|
||||
const header = buf.slice(0, headerEnd).toString('utf8');
|
||||
const m = /Content-Length:\s*(\d+)/i.exec(header);
|
||||
if (!m) {
|
||||
buf = buf.slice(headerEnd + 4);
|
||||
continue;
|
||||
}
|
||||
const len = Number(m[1]);
|
||||
const start = headerEnd + 4;
|
||||
if (buf.length < start + len) return;
|
||||
const body = buf.slice(start, start + len).toString('utf8');
|
||||
buf = buf.slice(start + len);
|
||||
try {
|
||||
handle(JSON.parse(body));
|
||||
} catch (e) {
|
||||
process.stderr.write(`parse error: ${e}\n`);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
const nl = buf.indexOf('\n');
|
||||
if (nl === -1) return;
|
||||
const line = buf.slice(0, nl).toString('utf8').trim();
|
||||
buf = buf.slice(nl + 1);
|
||||
if (!line || line.startsWith('Content-Length')) continue;
|
||||
try {
|
||||
handle(JSON.parse(line));
|
||||
} catch (e) {
|
||||
process.stderr.write(`ndjson parse error: ${e}\n`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
process.stdin.on('end', () => process.exit(0));
|
||||
Reference in New Issue
Block a user