使用说明内容（Markdown格式）

项目简介

Arc Reactor 是一个企业级 AI Agent 运行时，构建在 Spring AI 之上，围绕 ReAct 循环（Reasoning + Acting）设计，提供对资源、工具、提示模板等的统一管理与外部工具调用能力，并通过 MCP（Model Context Protocol）实现服务器端对 MCP 服务的注册、调度和治理。它支持多通道交付、严格的治理管线、审计日志以及可扩展的工具策略，适合搭建生产级的上下文服务后端。

主要功能点

ReAct 执行引擎：受控的工具调用循环，带有重试、上下文裁剪与结构化输出校验
5 阶段 Guard 管线：速率限制、输入长度、字符集规范化、分类等安全检查
4 点 Hook 生命周期：BeforeStart、AfterToolCall、BeforeResponse、AfterComplete，用于审计、计费和策略执行
动态 MCP 注册：运行时通过 REST API 注册并管理 MCP 服务器（STDIO/SSE），具备 per-server 访问策略
人工干预与工具策略：HITL 审批、工具策略引擎，按通道治理写工具调用
Prompt 模板版本管理：版本化的 Prompt 模板与评估
RAG 与向量检索集成：查询转换、PGVector、重排序和上下文注入
多代理编排、支持多通道交付（REST、SSE、Slack 等）
安全与合规：JWT 认证、审计日志、OpenTelemetry 等
部署友好：Kubernetes Helm、Docker、PostgreSQL 与 Flyway 数据迁移

安装步骤

克隆仓库并进入项目目录
系统依赖与环境变量设定（示例）：
- ARC_REACTOR_AUTH_JWT_SECRET：JWT 加密密钥，32 字节以上
- SPRING_DATASOURCE_URL/SPRING_DATASOURCE_USERNAME/SPRING_DATASOURCE_PASSWORD：PostgreSQL 数据库连接
- GEMINI_API_KEY：默认 LLM 提供方密钥（如 Gemini），也可配置 OpenAI/Anthropic 替代
启动方式（本地开发/快速启动）
- 使用 Gradle 启动：./gradlew :arc-app:bootRun
- 使用 Docker Compose 启动（含数据库、向量存储等组件）
运行后对外暴露的 API 入口
- MCP 服务器相关 API：/api/mcp/servers
- 其他管理与诊断端点：/api/auth、/actuator/health 等

服务器配置（MCP 客户端无需，需要给 MCP 服务端提供的注册配置，以下为示例描述）

服务器名称与描述，用于标识 MCP 服务端
transportType：STDIO 或 SSE，决定与 MCP 客户端的通信方式
config：包含启动服务器所需的命令及参数等
autoConnect：启动后是否自动连接到 MCP 客户端

示例 1（Filesystem 类工具，来自项目示例）： { "name": "filesystem", "description": "Local file tools", "transportType": "STDIO", "config": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }, "autoConnect": true }

示例 2（ Atlassian MCP 访问策略代理）： { "name": "atlassian", "transportType": "SSE", "config": { "url": "http://localhost:8085/sse", "adminToken": "change-me", "adminHmacRequired": true, "adminHmacSecret": "change-me-hmac" }, "autoConnect": true }

基本使用方法

启动后通过 /api/mcp/servers 注册 MCP 服务端
使用客户端配置文件指向已注册的 MCP 服务，客户端将通过 MCP 规范与服务器交互，获取上下文、调用工具、渲染 Prompt 等
管理端可对 MCP 服务器执行访问策略、动态更新、监控和审计

需要的准备与注意

确保 PostgreSQL/PGVector 等后端就绪，Flyway 迁移生效
安全性：尽量启用 JWT 验证、CORS、HSTS 等安全策略
生产环境中应对 MCP 服务器进行访问控制与审计策略配置

运行与测试

本地快速启动脚本、Gradle 构建或 Docker 方式任选其一
使用 MCP 服务注册 API 将 MCP 服务端注册并启动连接
验证端点与工具调用的路由、权限和日志

备注

Arc Reactor 的 MCP 支持强调动态服务器注册、工具治理和多通道交付能力，是真正面向 MCP 客户端的后端运行时框架，支持将外部工具/资源以标准化方式暴露给 LLM 客户端使用。

Arc Reactor