内容
# AutoForm_MCP
版本：`MCP_V1.8`
## 安装和连接
AutoForm_MCP 是一个可以独立运行的本地_stdio MCP服务器项目，用于让Codex、Claude Code、OpenCalw或其他MCP主机调用AutoForm辅助工具。克隆此仓库，或进入您在较大的`AUTO_AutoForm`工作区中收到的`AutoForm_MCP`文件夹。
AutoForm_MCP 是一个本地的标准输入/输出MCP服务器项目，用于辅助AutoForm工作流程。克隆此仓库，或进入您在较大的`AUTO_AutoForm`工作区中收到的`AutoForm_MCP`文件夹。
PowerShell:
```powershell
git clone https://github.com/txf0101/AutoForm_MCP.git AutoForm_MCP
cd AutoForm_MCP
conda env create -f environment.yml
conda activate afagent
python -c "import autoform_mcp_agent.mcp_server; print('mcp import ok')"
python -m autoform_mcp_agent.cli status
```
cmd:
```cmd
git clone https://github.com/txf0101/AutoForm_MCP.git AutoForm_MCP
cd AutoForm_MCP
conda env create -f environment.yml
conda activate afagent
python -c "import autoform_mcp_agent.mcp_server; print('mcp import ok')"
python -m autoform_mcp_agent.cli status
```
如果您已经在完整的`AUTO_AutoForm`工作区中，可以不克隆，直接进入子目录：
```powershell
cd AutoForm_MCP
conda env create -f environment.yml
conda activate afagent
python -c "import autoform_mcp_agent.mcp_server; print('mcp import ok')"
```
将以下`<repo-root>`替换为当前计算机上`AutoForm_MCP`文件夹的绝对路径。不要复制其他用户的绝对路径。
## Codex
将以下内容添加到`%USERPROFILE%\.codex\config.toml`中。仓库中也提供了相同内容的`codex_mcp_config.autoform-mcp.toml`模板。
```toml
[mcp_servers."autoform-mcp"]
command = 'conda'
args = ['run', '-n', 'afagent', 'python', '-m', 'autoform_mcp_agent.mcp_server']
startup_timeout_sec = 60
enabled = true
[mcp_servers."autoform-mcp".env]
PYTHONPATH = '<repo-root>'
```
如果Codex找不到`conda`，请改用您自己的`afagent`环境中的`python.exe`：
```toml
[mcp_servers."autoform-mcp"]
command = '<path-to-afagent-python.exe>'
args = ['-m', 'autoform_mcp_agent.mcp_server']
startup_timeout_sec = 60
enabled = true
[mcp_servers."autoform-mcp".env]
PYTHONPATH = '<repo-root>'
```
Windows上的常见位置包括`C:\Users\<user>\miniconda3\envs\afagent\python.exe`和`C:\ProgramData\miniconda3\envs\afagent\python.exe`。请使用目标计算机上实际存在的路径。
## Claude Code
PowerShell:
```powershell
claude mcp add --transport stdio --scope user --env PYTHONPATH="<repo-root>" autoform-mcp -- conda run -n afagent python -m autoform_mcp_agent.mcp_server
claude mcp list
claude mcp get autoform-mcp
```
cmd:
```cmd
claude mcp add --transport stdio --scope user --env PYTHONPATH="<repo-root>" autoform-mcp -- conda run -n afagent python -m autoform_mcp_agent.mcp_server
claude mcp list
claude mcp get autoform-mcp
```
如果命令行引号难以处理，可以使用JSON：
```powershell
claude mcp add-json autoform-mcp '{"type":"stdio","command":"conda","args":["run","-n","afagent","python","-m","autoform_mcp_agent.mcp_server"],"env":{"PYTHONPATH":"<repo-root>"}}'
```
## OpenCalw 或其他标准输入/输出MCP主机
在任何支持标准输入/输出的MCP客户端中使用相同的命令、参数和环境字段：
```json
{
"mcpServers": {
"autoform-mcp": {
"type": "stdio",
"command": "conda",
"args": ["run", "-n", "afagent", "python", "-m", "autoform_mcp_agent.mcp_server"],
"env": {
"PYTHONPATH": "<repo-root>"
}
}
}
}
```
## 手动服务器检查
仅运行此命令以检查stdio服务器是否可以启动。真正的MCP主机将保持进程打开，并通过标准输入和输出发送JSON-RPC消息。
```powershell
conda run -n afagent python -m autoform_mcp_agent.mcp_server
```
连接到主机后，按以下顺序验证：
1. 读取`autoform://status`，或调用`autoform_status_snapshot`。
2. 调用`autoform_discover_installation`。
3. 调用`autoform_result_blockers`以查看MCP_V1.8的结果审查边界。
4. 在您真正希望AutoForm运行时，保持执行工具在规划模式下。
5. 仅在确认项目、许可证、输出文件夹和可见桌面后使用`execute=true`。
## MCP_V1.8包含的内容
MCP_V1.8公开了112个`autoform_`工具和`autoform://status`资源。工具数量由`tests/test_mcp_tools.py`检查。
MCP_V1.8保留了V1.1的结果审查范围，并添加了一个较小、更安全的GUI后续路径：`autoform_result_set_view`现在接受`title_contains`和`target_pid`，因此主机可以切换到当前的AutoForm结果窗口，而无需重新打开示例项目。`autoform_r12_project_view_demo`还接受`view_sequence`；当省略此参数时，工具只打开或规划项目窗口，而不发送视图快捷键。
常用工具：
| 工具 | 用途 |
| --- | --- |
| `autoform_status_snapshot` | 读取本地健康状态、AutoForm安装发现、日志和能力覆盖。 |
| `autoform_discover_installation` | 查找本地AutoForm Forming安装和重要目录。 |
| `autoform_project_run` | 规划或执行复制后的`.afd`项目运行。实际执行需要`execute=true`。 |
| `autoform_official_sample_run_summary` | 从`run_manifest.json`汇总本地官方示例运行证据。 |
| `autoform_result_inventory` | 检查运行目录或工作区中的结果类文件。 |
| `autoform_result_plan_review` | 将结果审查请求转换为结构化计划。 |
| `autoform_result_set_view` | 规划或执行已验证的等轴测、俯视、正视和侧视快捷键；V1.8可以按窗口标题或PID定向。 |
| `autoform_result_play_forming_animation` | 使用受控播放配置文件或手动观察配置文件。 |
| `autoform_gui_window_snapshot` | 列出可见的AutoForm窗口和交互窗口。 |
| `autoform_gui_restore_window` | 在审计型GUI操作前恢复可见的AutoForm项目窗口。 |
MCP_V1.8不生成工程判断报告。它返回证据、就绪检查、GUI边界和审查计划。工程阈值规则属于后续可选输入。
## 可移植性规则
每台计算机都必须使用自己的仓库路径、Python环境路径、AutoForm安装和许可证。本仓库不包含AutoForm软件、许可证或专有示例项目。
如果自动发现AutoForm失败，请复制`.env.example`为`.env`，并仅填写当前计算机上不同的路径：
```powershell
Copy-Item .env.example .env
```
## 测试
如果Windows默认临时目录权限异常，请将临时目录放在项目内：
```powershell
$env:TEMP=(Resolve-Path .).Path + "\tmp\pytest_env"
$env:TMP=$env:TEMP
New-Item -ItemType Directory -Force -Path $env:TEMP | Out-Null
python -m pytest tests\test_mcp_tools.py tests\test_gui_automation.py tests\test_result_viewer.py tests\test_r12_demo.py tests\test_project_workflow.py tests\test_process.py -q --basetemp tmp\pytest_mcp
```
当前工作区MCP_V1.8的预期结果：
```text
57 passed
```
## 项目布局
| 路径 | 含义 |
| --- | --- |
| `autoform_mcp_agent/mcp_server.py` | 稳定的stdio MCP入口点。 |
| `autoform_mcp_agent/mcp_tools/` | 按工具系列分组的薄MCP包装。 |
| `autoform_mcp_agent/*.py` | MCP和CLI使用的共享业务功能。 |
| `tests/` | 重点的MCP、GUI、结果审查、进程和工作流测试。 |
| `codex_mcp_config.autoform-mcp.toml` | 便携式Codex/TOML MCP配置模板。 |
| `environment.yml` | 上述示例使用的Conda环境。 |
| `README.zh-CN.md` | 仅限中文的使用指南。 |
## 与AUTO_AutoForm的关系
`AUTO_AutoForm`可以将此文件夹作为子项目包含进去，以便较大的Agent应用程序具有本地MCP功能。此文件夹也可以作为名为`AutoForm_MCP`的GitHub仓库单独推送；独立仓库的根目录应该就是此文件夹，而不是整个`AUTO_AutoForm`工作区。
