mcp-cli-bridge AGENTS.md

McpHost 项目核心规则

📖 详细文档: README.md（架构设计、使用方式、问题排查）

📁 项目结构

目录树(关键部分)

McpHost/
├── McpHost.slnx                    # 解决方案文件
├── build.ps1                       # 本地构建脚本（AI智能体唯一可用的构建脚本）
├── buildAndNpm.ps1                 # CI/CD 专属发布脚本（⛔ AI智能体禁止使用）
├── release.ps1                     # 版本发布脚本（用户明确要求时 AI 可执行）
├── package.json                    # npm 包配置
│
├── src/                            # 源代码
│   ├── Common/                     # 共享库（DLL）
│   ├── Common.Contracts/           # 契约层（DLL）
│   ├── McpHost/                    # 主程序（EXE）
│   └── Plugins/                    # 外部插件（EXE）
│       ├── FileReaderCli/          # 文件读取 CLI
│       └── MemoryCli/              # 内存存储 CLI
│
├── lib/                            # 外部依赖
│   └── McpProtocol/                # MCP 协议库
│
├── tests/                          # 测试
│   ├── Benchmarks/                 # 性能测试
│   ├── E2E/                        # 端到端测试
│   ├── SecurityTests/              # 安全测试
│   └── UnitTests/                  # 单元测试
│
├── nuget.config                    # NuGet 配置
├── .github/workflows/              # CI/CD
└── AI交互文档/                      # AI 开发规范

⚡ 关键约束（修改代码前必读）

1. ❌ 禁止缓存CLI工具列表（未来可能上万命令）
2. ✅ 必须通过 build.ps1 发布到 publish/（buildAndNpm.ps1 是 CI/CD 专属，AI智能体禁止使用）
3. 🔒 src/Plugins/ 是外部插件，内部项目不得直接引用
4. 🎯 MCP Server 只暴露 Host 层工具，CLI工具通过 tool_execute 调用
5. 🚫 必须支持 NativeAOT 编译
   • 所有代码必须围绕 NativeAOT 编译构造
   • 否则 npm 包体积过大导致安装崩溃
   • 这是不可变原则
   • 检查项：动态类型、反射 emit、直接解析 JSON 均会导致 AOT 失败

🏗️ 架构依赖关系

Plugins (EXE) ──→ Common (DLL) ──→ Common.Contracts (DLL)
                         ↑
McpHost (EXE) ───────────┘     McpProtocol (DLL/NuGet)

组件	类型	约束
McpHost	EXE	MCP服务器主机
Common	DLL	共享基建
Common.Contracts	DLL	⚠️ 禁止添加实现（只能有接口/DTO）
Plugins/	EXE	⚠️ 不能引用 McpHost，只能引用 Common + Common.Contracts