All your AI agent sessions in one place — browse, search, resume. Rust + GPUI.
Rust
//! wake-mcp:把 Wake 的索引以 MCP(stdio 传输、JSON-RPC 2.0)**只读**暴露给别的
//! coding agent(Claude Code / Codex / Cursor …)。目标是"换一个 agent 不用重新
//! 解释自己做到哪了":对方按项目列最近会话、全文搜、读一段转录,全部来自本机
//! 索引与磁盘上的会话文件,零 LLM、零网络、不写库。
//!
//! 协议层手写而不引 rmcp:wake-core 全同步、没有 tokio,server 端真正要实现的
//! 只有 initialize / notifications/initialized / ping / tools/list / tools/call
//! 五个方法。消息按行分隔(stdio 传输规范:一行一条 JSON,不含裸换行),
//! stdout 只写协议,日志一律 stderr。需要 resources / prompts / sampling
//! 全家桶时再考虑换库。
//!
//! 索引库经 `Store::open_read_only` 打开——旁路进程绝不 `open_or_rebuild`,
//! 也不扫描;新鲜度靠 GUI 常驻的 watcher,每个工具返回都带"索引覆盖到的最新
//! 活动时间"。读会话是现场解析磁盘文件,不受索引新旧影响。
pub mod tools;
use std::io::{BufRead, Write};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use serde_json::{json, Value};
use crate::adapters::AgentAdapter;
use crate::db::Store;
use crate::models::AgentId;
/// 本方声明的协议版本(客户端请求的版本在 SUPPORTED 内就回显它,否则回这个)
pub const PROTOCOL_VERSION: &str = "2025-06-18";
/// 已知且工具子集完全兼容的版本
const SUPPORTED: [&str; 4] = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
pub const SERVER_NAME: &str = "wake";
pub const SERVER_VERSION: &str = env!("CARGO_PKG_VERSION");
/// agent 什么时候该用 Wake 的工具。默认 `Proactive`:用户提到之前的对话就用;`OnRequest`
/// (`wake-mcp --on-request` / `WAKE_ON_REQUEST=1`,#64)只在用户明确让它查 Wake 或过去的会话
/// 时才用——自己有记忆工具的人不想让 agent 为了回忆上下文自己去翻、花 token。只换下发给模型的
/// 说明与工具描述里"什么时候用"那一句,工具本身与返回内容不变;这是给模型的指引,不是锁,
/// 硬性拦住靠客户端的权限确认
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Usage {
Proactive,
OnRequest,
}
/// 插件用户改不了插件里的启动命令,靠这个环境变量打开 `Usage::OnRequest`;`wake-cli context`
/// (开会话钩子)见到它也不输出——判法只有 `Usage::from_env` 这一份,钩子与 MCP 永远出自同一对
/// 二进制,插件与 app 各自更新也不会一半生效
pub const ON_REQUEST_ENV: &str = "WAKE_ON_REQUEST";
impl Usage {
pub fn from_env() -> Self {
let value = std::env::var_os(ON_REQUEST_ENV);
// 不是 UTF-8 的值也是"设了"
Self::from_env_value(value.as_ref().map(|v| v.to_str().unwrap_or("1")))
}
/// 没设、空串、0 / false / no(不分大小写)是关,别的都是开
fn from_env_value(value: Option<&str>) -> Self {
match value.map(str::to_ascii_lowercase).as_deref() {
None | Some("" | "0" | "false" | "no") => Self::Proactive,
Some(_) => Self::OnRequest,
}
}
/// 一段给模型看的话 = 做什么 + 什么时候用 + 怎么用,只在被要求时使用只换中间那句(服务器说明与
/// 每个工具的描述共用,两种模式不各写一份全文)。`when` 为 None 的(wake_get_session 的描述没有
/// 触发句)默认就只有两段
pub(crate) fn compose(
self,
what: &str,
when: Option<&str>,
on_request: &str,
how: &str,
) -> String {
let when = match self {
Self::Proactive => when,
Self::OnRequest => Some(on_request),
};
match when {
Some(when) => format!("{what} {when} {how}"),
None => format!("{what} {how}"),
}
}
}
/// 随 initialize 下发给客户端的使用说明(LLM 会读),三段拼成:是什么、什么时候用、怎么用。
/// 默认那句是重点:模型对陌生工具默认不碰,问"最近在做什么"会去翻 git log——要点明会话
/// 记录里有而 git 里没有的东西(讨论、决策、试过的路、停在哪)
const INSTRUCTIONS_INTRO: &str = "Wake indexes every coding-agent session on this machine \
(Claude Code, Codex, Cursor, Gemini CLI, OpenCode and more) and exposes them read-only.";
const INSTRUCTIONS_WHEN: &str = "Use these tools whenever the user refers to earlier \
conversations or sessions with any AI coding agent: what was discussed, decided or tried, \
why something was done a certain way, where previous work stopped, or whether an error was \
seen before. Git history and the working tree do not contain that; Wake does.";
/// 只在被要求时使用换上的两句:服务器说明里一句、每个工具描述里一句,说的是同一件事,改一句
/// 就一起改
const INSTRUCTIONS_ON_REQUEST: &str = "The user wants these tools used only when they ask: \
call them when the user explicitly asks you to look something up in Wake or in their past \
sessions (\"check Wake\", \"search my past sessions for …\"), and don't call them on your \
own to recall context.";
pub(crate) const TOOL_ON_REQUEST: &str = "Call it only when the user explicitly asks you to \
look something up in Wake or in their past sessions; don't call it on your own to recall \
context.";
const INSTRUCTIONS_HOW: &str = "Start with wake_list_sessions (pass the current working \
directory as `project`) or wake_search, then read the relevant transcript with \
wake_get_session; wake_list_projects shows which projects have history. wake_list_memories \
lists the notes agents keep for themselves about a project (Claude Code and ZCode \
auto-memory, Codex memories); read one by passing its wake://memory/… reference to \
wake_get_session. Nothing here can modify a session or a memory file.";
pub fn instructions(usage: Usage) -> String {
usage.compose(
INSTRUCTIONS_INTRO,
Some(INSTRUCTIONS_WHEN),
INSTRUCTIONS_ON_REQUEST,
INSTRUCTIONS_HOW,
)
}
const JSONRPC_PARSE_ERROR: i64 = -32700;
const JSONRPC_INVALID_REQUEST: i64 = -32600;
const JSONRPC_METHOD_NOT_FOUND: i64 = -32601;
const JSONRPC_INVALID_PARAMS: i64 = -32602;
const JSONRPC_INTERNAL_ERROR: i64 = -32603;
/// 一个 MCP server 实例:持有只读 Store 与按库配置构造的 roster
pub struct McpServer {
store: Arc<Store>,
adapters: Vec<Box<dyn AgentAdapter>>,
transcripts: tools::TranscriptCache,
usage: Usage,
}
impl McpServer {
pub fn new(store: Arc<Store>, adapters: Vec<Box<dyn AgentAdapter>>, usage: Usage) -> Self {
Self {
store,
adapters,
transcripts: tools::TranscriptCache::default(),
usage,
}
}
/// 阻塞服务到 stdin EOF。每行一条消息;写失败(客户端已退出)即返回
pub fn serve(&self, input: impl BufRead, mut output: impl Write) -> std::io::Result<()> {
for line in input.lines() {
let line = line?;
if line.trim().is_empty() {
continue;
}
if let Some(reply) = self.handle_line(&line) {
output.write_all(reply.as_bytes())?;
output.write_all(b"\n")?;
output.flush()?;
}
}
Ok(())
}
/// 一行进、至多一行出(通知无回包)。批量数组逐条处理、按数组回;
/// 测试与 `wake-mcp call` 直接用它,不经 stdio
pub fn handle_line(&self, line: &str) -> Option<String> {
let msg: Value = match serde_json::from_str(line) {
Ok(v) => v,
Err(e) => {
return Some(
error_response(
Value::Null,
JSONRPC_PARSE_ERROR,
&format!("Parse error: {e}"),
)
.to_string(),
)
}
};
match msg {
Value::Array(items) => {
if items.is_empty() {
return Some(
error_response(Value::Null, JSONRPC_INVALID_REQUEST, "Invalid Request")
.to_string(),
);
}
let replies: Vec<Value> = items
.iter()
.filter_map(|m| self.handle_message(m))
.collect();
(!replies.is_empty()).then(|| Value::Array(replies).to_string())
}
other => self.handle_message(&other).map(|v| v.to_string()),
}
}
fn handle_message(&self, msg: &Value) -> Option<Value> {
let obj = match msg.as_object() {
Some(o) => o,
None => {
return Some(error_response(
Value::Null,
JSONRPC_INVALID_REQUEST,
"Invalid Request",
))
}
};
let id = obj.get("id").cloned();
let method = match obj.get("method").and_then(Value::as_str) {
Some(m) => m,
// 没有 method 的是"响应":本 server 从不向客户端发请求,静默丢弃
None => {
return id.filter(|id| !id.is_null()).and_then(|id| {
(!obj.contains_key("result") && !obj.contains_key("error"))
.then(|| error_response(id, JSONRPC_INVALID_REQUEST, "Invalid Request"))
})
}
};
let params = obj.get("params").cloned().unwrap_or(Value::Null);
// 通知(无 id)不回包,不管认不认识
let id = match id {
Some(id) if !id.is_null() => id,
_ => {
if method == "notifications/initialized" {
eprintln!("wake-mcp: client initialized");
}
return None;
}
};
let result = match method {
"initialize" => Ok(self.initialize(¶ms)),
"ping" => Ok(json!({})),
"tools/list" => Ok(json!({ "tools": tools::definitions_for(self.usage) })),
"tools/call" => self.call_tool(¶ms),
_ => Err((
JSONRPC_METHOD_NOT_FOUND,
format!("Method not found: {method}"),
)),
};
Some(match result {
Ok(result) => json!({ "jsonrpc": "2.0", "id": id, "result": result }),
Err((code, message)) => error_response(id, code, &message),
})
}
fn initialize(&self, params: &Value) -> Value {
let requested = params
.get("protocolVersion")
.and_then(Value::as_str)
.unwrap_or("");
let version = if SUPPORTED.contains(&requested) {
requested
} else {
PROTOCOL_VERSION
};
json!({
"protocolVersion": version,
"capabilities": { "tools": { "listChanged": false } },
"serverInfo": { "name": SERVER_NAME, "title": "Wake", "version": SERVER_VERSION },
"instructions": instructions(self.usage),
})
}
fn call_tool(&self, params: &Value) -> Result<Value, (i64, String)> {
let name = params.get("name").and_then(Value::as_str).ok_or((
JSONRPC_INVALID_PARAMS,
"tools/call needs a string `name`".to_string(),
))?;
let empty = json!({});
let args = params.get("arguments").unwrap_or(&empty);
if !args.is_object() && !args.is_null() {
return Err((
JSONRPC_INVALID_PARAMS,
"`arguments` must be an object".to_string(),
));
}
match tools::invoke(&self.store, &self.adapters, &self.transcripts, name, args) {
Ok(text) => Ok(tool_result(text, false)),
// 参数形状错(含未知工具名)是协议错误;执行失败(坏 key、解析失败)
// 是给 LLM 看的结果
Err(tools::ToolError::InvalidParams(m)) => Err((JSONRPC_INVALID_PARAMS, m)),
Err(tools::ToolError::Failed(m)) => Ok(tool_result(m, true)),
Err(tools::ToolError::Internal(m)) => Err((JSONRPC_INTERNAL_ERROR, m)),
}
}
}
fn tool_result(text: String, is_error: bool) -> Value {
json!({
"content": [{ "type": "text", "text": text }],
"isError": is_error,
})
}
fn error_response(id: Value, code: i64, message: &str) -> Value {
json!({ "jsonrpc": "2.0", "id": id, "error": { "code": code, "message": message } })
}
// ---------------------------------------------------------------- 安装辅助
/// 只读打开索引,并按库里的 location / remote host 配置建 roster(不变量
/// 8⑥:否则自定义根与远程缓存里的会话找不到能读它的 adapter)。旁路进程
/// (wake-mcp / wake-cli)共用这一条——**绝不 open_or_rebuild**,那会把 GUI
/// 正在写的库挪走重建
pub fn open_index(db: &Path) -> Result<(Arc<Store>, Vec<Box<dyn AgentAdapter>>), String> {
let store = Arc::new(Store::open_read_only(db).map_err(|e| format!("{e:#}"))?);
let adapters = crate::adapters::create_adapters_for(&store);
Ok((store, adapters))
}
/// 与本进程同目录的某个辅助可执行文件(Windows 补 .exe)。打包时辅助 bin 与
/// Wake 主程序并排:macOS 在 Contents/MacOS,Linux/Windows 同目录。
/// current_exe 是系统调用,**别在 render 里问**——GUI 一律开窗时算一次
pub fn sibling_named(stem: &str) -> Option<PathBuf> {
let exe = std::env::current_exe().ok()?;
let name = if cfg!(target_os = "windows") {
format!("{stem}.exe")
} else {
stem.to_string()
};
Some(exe.parent()?.join(name))
}
/// sibling_named 的"在才算"版:不存在或不是文件给 None。要显示"它该在哪"(Settings
/// 的 Not found 提示)用 sibling_named,要拿一个能跑的用这个
pub fn sibling_file(stem: &str) -> Option<PathBuf> {
sibling_named(stem).filter(|p| p.is_file())
}
/// 一段可复制的接入配置
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SetupSnippet {
/// 客户端名("Claude Code")
pub client: &'static str,
/// 对应的 agent(MCP clients 那一行的品牌图标)
pub agent: AgentId,
/// 怎么用这段("Run in a terminal" / "Add to ~/.codex/config.toml")
pub hint: &'static str,
/// 复制钮的说明("Copy command" / "Copy config";Connect 页的复制钮只有图标,这句进 tooltip)
pub copy_label: &'static str,
pub text: String,
}
/// 三家客户端的接入片段(UI 的 Connect 页与 `wake-mcp setup` 同源)。路径一律按 JSON 字符串
/// 引好——TOML basic string 与 JSON 的转义子集兼容,一个写法同时给 TOML 与 JSON 两种配置用,
/// Windows 的反斜杠与含空格路径都安全
pub fn setup_snippets(bin: &Path) -> Vec<SetupSnippet> {
let quoted = serde_json::to_string(&bin.to_string_lossy()).unwrap_or_default();
vec![
SetupSnippet {
client: "Claude Code",
agent: AgentId::ClaudeCode,
hint: "Run in a terminal",
copy_label: "Copy command",
text: format!("claude mcp add --scope user wake -- {quoted}"),
},
SetupSnippet {
client: "Codex",
agent: AgentId::Codex,
hint: "Add to ~/.codex/config.toml",
copy_label: "Copy config",
text: format!("[mcp_servers.wake]\ncommand = {quoted}"),
},
SetupSnippet {
client: "Cursor",
agent: AgentId::Cursor,
hint: "Merge into ~/.cursor/mcp.json",
copy_label: "Copy config",
text: format!(
"{{\n \"mcpServers\": {{\n \"wake\": {{ \"command\": {quoted} }}\n }}\n}}"
),
},
]
}
#[cfg(test)]
mod tests {
use super::*;
/// initialize 回的 instructions 是 agent 唯一常驻的一段说明:每个工具都得点到名,
/// 否则新工具对只读这段的 agent 就是隐形的(2026-09-21 review:加 wake_list_memories
/// 时漏了这里)
#[test]
fn instructions_mention_every_tool() {
for usage in [Usage::Proactive, Usage::OnRequest] {
let text = instructions(usage);
for name in tools::NAMES {
assert!(text.contains(name), "{usage:?} 的说明没提到 {name}");
}
}
}
/// 只在被要求时使用:只换"什么时候用"那一句,开头与用法照旧
#[test]
fn on_request_only_changes_when_to_use() {
let proactive = instructions(Usage::Proactive);
assert!(proactive.contains(INSTRUCTIONS_WHEN));
assert_eq!(
instructions(Usage::OnRequest),
proactive.replace(INSTRUCTIONS_WHEN, INSTRUCTIONS_ON_REQUEST)
);
}
#[test]
fn the_on_request_switch_reads_like_a_flag() {
for off in [None, Some(""), Some("0"), Some("false"), Some("No")] {
assert_eq!(Usage::from_env_value(off), Usage::Proactive, "{off:?}");
}
for on in ["1", "true", "YES", "on"] {
assert_eq!(Usage::from_env_value(Some(on)), Usage::OnRequest, "{on}");
}
}
#[test]
fn snippets_quote_paths_for_every_client() {
let snippets = setup_snippets(Path::new(
"/Applications/My Apps/Wake.app/Contents/MacOS/wake-mcp",
));
assert_eq!(snippets.len(), 3);
assert_eq!(
snippets[0].text,
"claude mcp add --scope user wake -- \"/Applications/My Apps/Wake.app/Contents/MacOS/wake-mcp\""
);
assert!(snippets[1]
.text
.starts_with("[mcp_servers.wake]\ncommand = \"/Applications/My Apps/"));
let cursor: Value =
serde_json::from_str(&snippets[2].text).expect("cursor snippet is valid JSON");
assert_eq!(
cursor["mcpServers"]["wake"]["command"],
"/Applications/My Apps/Wake.app/Contents/MacOS/wake-mcp"
);
let win = setup_snippets(Path::new(r"C:\Program Files\Wake\wake-mcp.exe"));
assert!(win[1]
.text
.contains(r#"command = "C:\\Program Files\\Wake\\wake-mcp.exe""#));
}
}