Josh Gpt MCP

JoshGPT MCP

用于JoshGPT工具执行和角色路由编排的容器化MCP服务。

目的

此存储库包含三个运行时服务：

1. toolhost （工具主机）

- 文件/搜索工具 - 可选命令执行工具

1. dispatcher （能力）

- 角色工作者的任务路由/状态 - 主管问答链接

1. supervisor （能力）

- 规范食品法典监督决策引擎(ask_codex_supervisor) - 本阶段支持Codex CLI

建筑

• 单一仓库，独立的服务/容器。
• 调度员和主管是能力，而不是角色。
• 主管能力使用规范 ask-codex-supervisor 合同。
• 角色工作者注入升级有效载荷并消耗主管决策。

合同

规范主管模式：

• contracts/ask-codex-supervisor.request.schema.json
• contracts/ask-codex-supervisor.response.schema.json
• contracts/ask-codex-supervisor.tool.json

故障安全规则：

• 如果有效负载验证或Codex运行时执行失败，监督程序将返回一个有效的确定性模式 pause_for_human 回应。

服务和工具

1） 工具主机(toolhost)

只读：

• list_files
• read_file
• search_text
• server_info

执行（策略门控）：

• run_host_command
• run_container_command

2） 调度员(dispatcher)

• dispatch_role_task
• claim_next_task
• set_task_status
• submit_supervisor_question
• list_pending_supervisor_questions
• respond_supervisor_question
• get_task_status
• list_role_queues
• dispatcher_info

3） 主管能力(supervisor)

• ask_codex_supervisor

快速开始

cp .env.example .env
# set shared tokens before start

docker compose up --build -d
docker compose ps

默认端口：

• 工具主机： 127.0.0.1:8787
• 调度员： 127.0.0.1:8788
• 主管能力： 127.0.0.1:8789

Codex CLI登录（主管）

主管要求经过认证 codex 监控器运行时内的CLI会话。

docker exec -it jgp-supervisor codex login --device-auth
docker exec jgp-supervisor codex login status

本地运行（无Docker）

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# tool-host
python src/joshgpt_mcp_server.py

# dispatcher (separate terminal)
python src/dispatcher_mcp_server.py

# supervisor capability (separate terminal)
python src/supervisor_capability_server.py

环境

工具主机

• JOSHGPT_MCP_* 变量在 .env.example

调度员

• JOSHGPT_DISPATCHER_BIND_HOST
• JOSHGPT_DISPATCHER_BIND_PORT
• JOSHGPT_DISPATCHER_TRANSPORT
• JOSHGPT_DISPATCHER_PUBLISH_HOST
• JOSHGPT_DISPATCHER_PUBLISH_PORT
• JOSHGPT_DISPATCHER_DB_PATH
• JOSHGPT_DISPATCHER_REQUIRE_SHARED_TOKEN
• JOSHGPT_DISPATCHER_SHARED_TOKEN

主管能力

• JOSHGPT_SUPERVISOR_BIND_HOST
• JOSHGPT_SUPERVISOR_BIND_PORT
• JOSHGPT_SUPERVISOR_TRANSPORT
• JOSHGPT_SUPERVISOR_PUBLISH_HOST
• JOSHGPT_SUPERVISOR_PUBLISH_PORT
• JOSHGPT_SUPERVISOR_REQUIRE_SHARED_TOKEN
• JOSHGPT_SUPERVISOR_SHARED_TOKEN
• JOSHGPT_SUPERVISOR_CODEX_CLI_BIN
• JOSHGPT_SUPERVISOR_CODEX_CLI_TIMEOUT_SECONDS
• JOSHGPT_SUPERVISOR_CODEX_MODEL
• JOSHGPT_SUPERVISOR_CODEX_STATE_VOLUME

烟雾检查

python3 -m py_compile src/joshgpt_mcp_server.py src/dispatcher_mcp_server.py src/supervisor_capability_server.py

docker compose logs --tail=100 dispatcher
docker compose logs --tail=100 supervisor

端到端角色/主管循环（仅限MCP）

从repo根运行规范烟雾脚本：

.venv/bin/python scripts/smoke_worker_supervisor_loop.py --summary-only

带有显式令牌/端点的可选示例：

.venv/bin/python scripts/smoke_worker_supervisor_loop.py \
  --dispatcher-url http://127.0.0.1:8788/mcp \
  --supervisor-url http://127.0.0.1:8789/mcp \
  --dispatcher-shared-token replace-me-dispatcher-token \
  --supervisor-shared-token replace-me-supervisor-token \
  --worker-role-slug implementation-specialist \
  --supervisor-role-slug hr-ai-agent-specialist \
  --requested-decision next_step

脚本序列：

• 调度任务
• 认领任务
• 提交主管问题
• 呼叫 ask_codex_supervisor
• 记录主管的回应
• 获取最终任务状态/事件

备注

• Dispatcher将SQLite用于MVP状态。
• 默认情况下，调度器和监督工具启用了共享令牌保护。
• 在此阶段，主管后端仅为Codex CLI。