feat(mcp): 落地 MCP 工具层 —— 4 元工具 + 分层加载 + 进程内适配器

- 新增 crates/sspf-mcp:registry / jsonrpc / server / 4 个元工具(context·discover·describe·call)
- 内核新增 mcp_adapter.rs(NativeAdapter,直接调 AppState)与 `--mcp` 子命令
- 工具定义自带五段自提示(含 pitfalls/examples),示例必须能被测试跑通
- 新增 scripts/mcp-smoke.sh(13 条)与 docs/mcp.md(接入说明)
- 影响:协议层只暴露 4 个工具(常驻约 1.8K token);业务失败返回结构化 error 而非协议错
- 踩坑记录:内嵌 PG 会抢 fd 0/1,必须在开库前 detach 标准流;tokio 的 stdin 在管道上 ENXIO
This commit is contained in:
admin committed 2026-10-31 10:29:14 +08:00
1 parent b11ec26106
commit 217dadf008
20 files changed
+3173 -11

No files matched your search

+6
View File
@@ -40,3 +40,9 @@ sspf-contract = { path = "../../crates/sspf-contract" }
# 存储层(db / config)—— 不认识 HTTP,可被低代码引擎、CLI、MCP 适配器共用
sspf-store = { path = "../../crates/sspf-store" }
# MCP 工具层(元工具 + 分层加载)—— 内核实现它的 PlatformAdapter,反向依赖
sspf-mcp = { path = "../../crates/sspf-mcp" }
# 仅用于 MCP 模式的 `dup2`(把 fd 1 让给 stderr,见 main.rs)
libc = { workspace = true }
+1
View File
@@ -13,6 +13,7 @@
//! 🔴 另加 [`bootstrap`] = **装配根**(唯一同时认识平台层与业务层的地方)。
pub mod bootstrap;
pub mod mcp_adapter;
pub mod modules;
pub mod platform;
pub mod routes;
+117 -5
View File
@@ -22,6 +22,7 @@ use std::path::PathBuf;
use std::sync::Arc;
use ssw_platform::bootstrap;
use ssw_platform::mcp_adapter;
use ssw_platform::modules;
use ssw_platform::platform::cipher;
use ssw_platform::platform::config::Config;
@@ -71,12 +72,23 @@ enum Cmd {
EncMissing,
/// `--help` / `-h` ⇒ 打印用法,退出码 **0**。
Help,
/// `--mcp` ⇒ 起 MCP stdio 服务(不监听端口),退出码 **0**。
Mcp,
/// 未知参数 ⇒ 用法错,退出码 **2**。
Unknown(String),
/// 无参数 ⇒ 起服务。
Serve,
}
/// 运行时形态(`run()` 的两个分支)。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum RunMode {
/// HTTP 服务(默认)。
Serve,
/// MCP stdio 服务(`--mcp`)—— 与 HTTP 共用同一套装配与同一个库。
Mcp,
}
/// 解析命令行参数(**纯函数**:不读环境变量、不退出进程、不打日志)。
///
/// 🔴 语义逐字照搬契约 §10 的子命令条:
@@ -91,6 +103,7 @@ fn parse_args(args: &[String]) -> Cmd {
Some(plain) => Cmd::Enc(plain.clone()),
None => Cmd::EncMissing,
},
Some("--mcp") => Cmd::Mcp,
Some("--help") | Some("-h") => Cmd::Help,
Some(other) => Cmd::Unknown(other.to_string()),
None => Cmd::Serve,
@@ -99,12 +112,12 @@ fn parse_args(args: &[String]) -> Cmd {
/// 子命令的**退出码**(纯函数 ⇒ 可单测)。
///
/// 🔴 `Cmd::Serve` ⇒ 0:起服务**不因用法出错而退出**(实际不会调用 `exit`)。
/// 🔴 `Cmd::Serve` / `Cmd::Mcp` ⇒ 0:起服务**不因用法出错而退出**(实际不会调用 `exit`)。
fn exit_code(cmd: &Cmd) -> i32 {
match cmd {
Cmd::Enc(_) | Cmd::Help => 0,
Cmd::EncMissing | Cmd::Unknown(_) => 2,
Cmd::Serve => 0,
Cmd::Serve | Cmd::Mcp => 0,
}
}
@@ -133,10 +146,17 @@ async fn main() {
print_usage();
std::process::exit(exit_code(&cmd));
}
Cmd::Serve => {}
// 两个「起服务」形态共用同一套装配(见 `run`),只是收尾不同。
Cmd::Serve | Cmd::Mcp => {}
}
if let Err(msg) = run().await {
let mode = if cmd == Cmd::Mcp {
RunMode::Mcp
} else {
RunMode::Serve
};
if let Err(msg) = run(mode).await {
eprintln!("[启动失败] {msg}");
std::process::exit(1);
}
@@ -151,6 +171,7 @@ fn print_usage() {
println!();
println!("用法:");
println!(" ssw-platform 启动 HTTP 服务(默认端口 30010)");
println!(" ssw-platform --mcp 启动 MCP stdio 服务(供 AI 直接驱动,不监听端口)");
println!(" ssw-platform --enc <明文> 打印登录口令密文(hex),退出码 0");
println!(" ssw-platform --help 打印本用法,退出码 0");
println!();
@@ -160,8 +181,82 @@ fn print_usage() {
println!(" PGLITE_DIR pglite 数据目录;设成 memory:// 用临时库(进程退出即销毁)");
}
/// 把标准流整个让给内嵌 PostgreSQL,返回**复制出来**的协议通道(读, 写)。
///
/// 🔴 为什么必须这么干(实测踩出来的):
///
/// 1. **stdout**:PG 会往 fd 1 打 `PostgreSQL stand-alone backend 17.5`。
/// MCP 的 stdio 是 NDJSON(一行一个 JSON),混进任何非 JSON 行客户端就崩。
/// 2. **stdin**:PG 的 **single-user 后端直接占用 fd 0**(那个 `backend>` 提示符就是它在读)。
/// 不处理的话,我们读 stdin 会拿到 `ENXIO (Device not configured)` ——
/// 因为 PG 已经把它当成 SQL 输入通道了。
///
/// ⇒ 开库**之前**先 `dup` 出协议 fd,再把 fd 0/1 指向 `/dev/null` 与 stderr。
/// 之后 PG 随便折腾标准流,协议走专属通道。
///
/// 返回的 `(File, File)` **拥有**那两个 fd,drop 时关闭。
#[cfg(unix)]
fn detach_stdio_for_mcp() -> std::io::Result<(std::fs::File, std::fs::File)> {
use std::os::unix::io::{FromRawFd, RawFd};
// SAFETY: 全是 fd 级操作;任一步失败都显式回滚已拿到的 fd,不留半改状态。
unsafe {
let in_fd: RawFd = libc::dup(0);
if in_fd < 0 {
return Err(std::io::Error::last_os_error());
}
let out_fd: RawFd = libc::dup(1);
if out_fd < 0 {
libc::close(in_fd);
return Err(std::io::Error::last_os_error());
}
let null_path = c"/dev/null".as_ptr();
let null_fd = libc::open(null_path, libc::O_RDWR);
if null_fd < 0 {
let e = std::io::Error::last_os_error();
libc::close(in_fd);
libc::close(out_fd);
return Err(e);
}
// PG 的 single-user 后端:stdin 读 /dev/null(立刻 EOF),stdout 进 stderr(日志可见)。
libc::dup2(null_fd, 0);
libc::dup2(2, 1);
libc::close(null_fd);
Ok((
std::fs::File::from_raw_fd(in_fd),
std::fs::File::from_raw_fd(out_fd),
))
}
}
#[cfg(not(unix))]
fn detach_stdio_for_mcp() -> std::io::Result<(std::fs::File, std::fs::File)> {
Err(std::io::Error::new(
std::io::ErrorKind::Unsupported,
"MCP 模式暂只支持 unix(需要 dup2)",
))
}
/// 启动装配(契约 §10 的 1~7 步)。
async fn run() -> Result<(), String> {
///
/// 🔴 `--mcp` 与 HTTP 走**同一套装配**(同库、同种子、同白名单自检),
/// 只是第 6/7 步换成 MCP stdio —— 保证「AI 通过 MCP 看到的库」与
/// 「前端通过 HTTP 看到的库」是同一个,不会出现两套环境。
async fn run(mode: RunMode) -> Result<(), String> {
// ---- MCP 形态:**抢在开库之前**把标准流让给内嵌 PG,协议走专属 fd ----
//
// 🔴 见 `detach_stdio_for_mcp` 的注释:PG 的 single-user 后端会同时占用
// stdin(读 SQL)与 stdout(打 `backend>`)。不抢在开库前处理,
// MCP 的 NDJSON 流第一时间就被污染,读 stdin 也会 ENXIO。
let mcp_io = if mode == RunMode::Mcp {
Some(detach_stdio_for_mcp().map_err(|e| format!("MCP 模式接管标准流失败: {e}"))?)
} else {
None
};
// ---- 第 1 步:定位项目根(与 cwd 解耦)----
let project_dir = resolve_project_dir();
@@ -222,6 +317,23 @@ async fn run() -> Result<(), String> {
// 🔴 保留一个 `Db` 句柄用于**停机时优雅关闭**嵌入式 PG(`state` 会被 `build_app` 吃掉)。
let db_for_shutdown = state.db.clone();
// ---- MCP 形态:装配到这儿就够了,不建路由、不绑端口 ----
//
// 🔴 工具层与 HTTP 层共用同一个 `AppState` ⇒ AI 通过 MCP 改的数据,
// 前端刷新就能看到;反之亦然。这是「人机协作」在架构上的前提。
if let Some((reader, writer)) = mcp_io {
eprintln!(
"[mcp] sspf-mcp v{} 已就绪(stdio / NDJSON,数据目录 {})",
sspf_mcp::VERSION,
config.pg_dir.display()
);
let adapter = Arc::new(mcp_adapter::NativeAdapter::new(state));
return sspf_mcp::Server::new(adapter)
.serve_blocking_stdin(reader, writer)
.await
.map_err(|e| format!("MCP stdio 服务异常退出: {e}"));
}
// ---- 第 6 步:路由装配 + 三层兜底 ----
// 🔴 装配链**只有一份**:`routes::build_app` —— S25 的顺序(`.fallback()` 在两个
// `.layer()` **之前**、`.with_state()` 是**链尾**)就写在那儿。
+324
View File
@@ -0,0 +1,324 @@
//! mcp_adapter —— 内核侧实现 `sspf_mcp::PlatformAdapter`(**进程内直调**)。
//!
//! ## 为什么放在内核里,而不是 sspf-mcp 里
//!
//! 依赖方向是 `kernel → sspf-mcp → sspf-contract`(见 `PLAN.md` §3.2 AR5)。
//! MCP 层不认识 `AppState`、不认识 `Db` —— 所以「怎么拿数据」只能由内核实现。
//!
//! 好处是同一个 `sspf-mcp` 还能被 `BaselineHttpAdapter` 复用(P4 对账时打 Java 后端),
//! 两边的工具契约完全一致。
//!
//! ## 为什么不走 HTTP 回环
//!
//! `--mcp` 形态与 HTTP 形态**共用同一个 `AppState`**(同库、同连接、同会话表)。
//! 走 HTTP 会多一层序列化 + 需要额外端口 + 需要先登录拿 token,
//! 而 AI 本地驱动开发时没有「登录」这个概念 —— 它就是这个进程的主人。
//!
//! ## 🔴 但没有权限上下文
//!
//! 进程内直调意味着**绕过登录与菜单守卫**。这在本地开发是特性(AI 就是管理员),
//! 在多用户部署是风险。⇒ 未来若把 MCP 暴露到网络,必须走 `BaselineHttpAdapter`
//! 带上真实 token,不能用本适配器。
use serde_json::{json, Value};
use crate::platform::db::valid_table;
use crate::platform::state::AppState;
use sspf_mcp::adapter::{BoxFut, EnvInfo, PlatformAdapter, ToolError};
/// 进程内适配器。
pub struct NativeAdapter {
state: AppState,
}
impl NativeAdapter {
/// 用装配好的状态构造。
pub fn new(state: AppState) -> Self {
Self { state }
}
/// 取主系统 id(`base_system.f_is_main=1`),查不到就回落常量。
async fn main_system_id(&self) -> String {
self.state
.db
.scalar_text("SELECT f_id FROM base_system WHERE f_is_main = 1 LIMIT 1")
.await
.ok()
.flatten()
.unwrap_or_else(|| "mainSystem".to_string())
}
/// 数当前 schema 下的表(健康检查口径,与 `/api/health` 一致)。
async fn table_count(&self) -> usize {
self.state
.db
.scalar_text(
"SELECT count(*)::text FROM information_schema.tables \
WHERE table_schema = 'public' AND table_type = 'BASE TABLE'",
)
.await
.ok()
.flatten()
.and_then(|s| s.parse().ok())
.unwrap_or(0)
}
}
/// 把 pglite 错误转成结构化的工具错误(AI 能看懂的那种)。
fn db_err(e: pglite::Error) -> ToolError {
ToolError::new("DB_ERROR", format!("数据库错误: {e}"))
.hint("多数是 SQL 与当前 schema 不匹配;先 schema.table.list 确认表在不在")
.retryable()
}
impl PlatformAdapter for NativeAdapter {
fn describe_env<'a>(&'a self) -> BoxFut<'a, EnvInfo> {
Box::pin(async move {
let system_id = self.main_system_id().await;
let tables = self.table_count().await;
// 能力域 = 注册表里实际有工具的分类(不靠硬编码清单,避免「声称支持但没工具」)
let mut caps: Vec<String> = sspf_mcp::Registry::global()
.all()
.iter()
.map(|t| t.category.as_str().to_string())
.collect();
caps.sort();
caps.dedup();
EnvInfo {
backend: "native".to_string(),
version: env!("CARGO_PKG_VERSION").to_string(),
app_code: system_id.clone(),
system_id,
// 🔴 进程内适配器没有登录态:它本身就是管理员视角。
user: None,
tables,
capabilities: caps,
}
})
}
fn invoke<'a>(&'a self, op: &'a str, args: Value) -> BoxFut<'a, Result<Value, ToolError>> {
Box::pin(async move {
match op {
// ------------------------------------------------ 上下文
"context.get" => {
let system_id = self.main_system_id().await;
let tables = self.table_count().await;
Ok(json!({
"backend": "native",
"version": env!("CARGO_PKG_VERSION"),
"app_code": system_id,
"system_id": system_id,
"tables": tables,
}))
}
// ------------------------------------------------ 表清单
"schema.table.list" => {
let prefix = args
.get("prefix")
.and_then(Value::as_str)
.unwrap_or("")
.to_string();
let rows = self
.state
.db
.query_json(
"SELECT t.table_name AS \"name\", \
(SELECT count(*) FROM information_schema.columns c \
WHERE c.table_schema = t.table_schema AND c.table_name = t.table_name)::int \
AS \"columns\" \
FROM information_schema.tables t \
WHERE t.table_schema = 'public' AND t.table_type = 'BASE TABLE' \
ORDER BY t.table_name",
)
.await
.map_err(db_err)?;
let filtered: Vec<Value> = rows
.into_iter()
.filter(|r| {
prefix.is_empty()
|| r["name"].as_str().is_some_and(|n| n.starts_with(&prefix))
})
.collect();
Ok(json!({
"count": filtered.len(),
"prefix": if prefix.is_empty() { Value::Null } else { json!(prefix) },
"tables": filtered,
}))
}
// ------------------------------------------------ 表结构
"schema.table.describe" => {
let raw = args.get("table").and_then(Value::as_str).unwrap_or("");
// 🔴 表名只走白名单(`valid_table`),绝不拼接用户输入
let Some(table) = valid_table(raw) else {
return Err(ToolError::new(
"INVALID_TABLE",
format!("表名不合法: {raw}"),
)
.field("table")
.hint("只接受小写字母/数字/下划线,且必须以 f_ 或业务前缀开头")
.next(
"schema.table.list",
json!({}),
"先列出所有表,再挑一个",
));
};
let rows = self
.state
.db
.query_json_params(
"SELECT column_name AS \"name\", \
data_type AS \"type\", \
is_nullable AS \"nullable\", \
COALESCE(column_default, '') AS \"default\" \
FROM information_schema.columns \
WHERE table_schema = 'public' AND table_name = $1 \
ORDER BY ordinal_position",
&[&table],
)
.await
.map_err(db_err)?;
if rows.is_empty() {
return Err(ToolError::new(
"TABLE_NOT_FOUND",
format!("表 {table} 不存在"),
)
.field("table")
.next("schema.table.list", json!({}), "确认表名"));
}
Ok(json!({
"table": table,
"column_count": rows.len(),
"columns": rows,
}))
}
// ------------------------------------------------ 菜单树
"menu.tree" => {
let flat = args.get("flat").and_then(Value::as_bool).unwrap_or(false);
let system_id = self.main_system_id().await;
let rows = self
.state
.db
.query_json_params(
"SELECT f_id AS \"id\", \
f_parent_id AS \"parentId\", \
f_full_name AS \"fullName\", \
COALESCE(f_en_code, '') AS \"enCode\", \
COALESCE(f_url_address, '') AS \"urlAddress\", \
f_type AS \"type\", \
COALESCE(f_sort_code, 0) AS \"sortCode\" \
FROM base_module \
WHERE f_delete_mark = 0 AND f_system_id = $1 \
ORDER BY f_sort_code, f_full_name",
&[&system_id],
)
.await
.map_err(db_err)?;
if flat {
return Ok(json!({
"system_id": system_id,
"mode": "flat",
"count": rows.len(),
"menus": rows,
}));
}
// 建树(父不存在的节点挂到根,避免脏数据导致整棵树消失)
let mut children: std::collections::BTreeMap<String, Vec<Value>> =
std::collections::BTreeMap::new();
let mut ids = std::collections::HashSet::new();
for r in &rows {
if let Some(id) = r["id"].as_str() {
ids.insert(id.to_string());
}
}
for r in rows {
let parent = r["parentId"].as_str().unwrap_or("0").to_string();
let key = if ids.contains(&parent) { parent } else { "0".to_string() };
children.entry(key).or_default().push(r);
}
/// 递归组装(深度上限防御脏数据造成环)。
fn build(
parent: &str,
children: &std::collections::BTreeMap<String, Vec<Value>>,
depth: usize,
) -> Vec<Value> {
if depth > 32 {
return Vec::new();
}
let Some(nodes) = children.get(parent) else {
return Vec::new();
};
nodes
.iter()
.map(|n| {
let id = n["id"].as_str().unwrap_or("").to_string();
let mut node = n.clone();
node["children"] = Value::Array(build(&id, children, depth + 1));
node
})
.collect()
}
let tree = build("0", &children, 0);
Ok(json!({
"system_id": system_id,
"mode": "tree",
"count": ids.len(),
"menus": tree,
}))
}
other => Err(ToolError::new(
"OP_NOT_IMPLEMENTED",
format!("原生适配器还没实现 op: {other}"),
)
.hint("该工具已注册但后端未实现;先在 tools/mod.rs 里摘掉或补实现")
.next(
"sspf_discover",
json!({}),
"看看还有哪些工具可用",
)),
}
})
}
}
#[cfg(test)]
mod tests {
use super::*;
/// 🔴 表名白名单必须挡住注入尝试 —— 这是 `schema.table.describe` 的唯一安全边界。
#[test]
fn table_name_whitelist_blocks_injection() {
assert!(valid_table("asset_data_resource").is_some());
assert!(valid_table("base_user").is_some());
assert!(valid_table("users; DROP TABLE base_user").is_none());
assert!(valid_table("base_user--").is_none());
assert!(valid_table("").is_none());
}
/// 错误对象必须带 next_actions(AI 自纠的依据)。
#[test]
fn db_error_carries_hint_and_is_retryable() {
// 构造一个 pglite 错误比较麻烦,这里只校验 ToolError 的形状约定
let e = ToolError::new("DB_ERROR", "x").retryable().hint("y");
assert!(e.retryable);
assert_eq!(e.hints.len(), 1);
}
}