Skip to main content
Glama
SciTrace MCP Server

SciTrace MCP Server

by Mobai-read

SciTrace

PyPI Python License CI

English · 中文

MCP 服务器 — 让 AI Agent 的推理链从上下文窗口搬进数据库。

一行 MCP 配置。两个 Tool。Agent 每次调用 build_trace 记录一个推理步骤,query_trace 随时拉回历史。数据在 SQLite,不在上下文窗口。

🚀 30 秒看效果:

pip install scitrace
scitrace-demo --viz      # 写入一条钙钛矿科研演示链 + 生成可视化

用浏览器打开生成的 scitrace-demo.html:悬停节点看摘要、点击看详情面板、双击折叠子树——找一找那条紫色虚线(backtrack),那是推理链最精彩的部分。


为什么不用提示词/Skill?

提示词和 Skill 能做到"让 Agent 输出结构化推理",但做不到以下五件事。

1. 上下文窗口是稀缺资源,不是仓库

提示词规定输出结构

SciTrace

10 步后上下文

10 段完整 JSON(500-1500 tokens)堆在窗口里

10 行短调用记录,数据全在 SQLite

50 步后

Agent 开始"遗忘"前面的步骤——窗口被历史推理挤满

上下文干净,需要时 query_trace 精确拉回

跨会话

新会话 = 全部丢失

SQLite 持久化,新会话直接查

提示词方式里,推理链越积越多,抢真实任务的 token 配额。SciTrace 把数据搬出去——上下文窗口用于思考,SQLite 用于存储。

2. 提示词只写不查,SciTrace 可查

提示词: "之前那个假设是什么来着?" → Agent 在 3000 tokens 的聊天记录里翻找 → 可能翻到也可能漏掉

SciTrace: query_trace(type="hypothesis") → 精确返回。不看聊天记录。

结构化查询 = type=backtrack 直接找到所有失败回溯点,type=experiment 列出全部实验步骤,trace_id=xxx 看完整推理链。提示词做不到。

3. DAG 不是扁平的

提示词让 Agent 输出顺序列表。但科研推理不是线性的——它分叉、回溯、有依赖。

h1 (假设) → a1 (分析) → e1 (实验) → b1 (回溯) → e2 (修正) → v1 (验证) → c1 (结论)
                                          ↑
                                    parent_id 显式声明依赖

parent_id 把扁平的列表变成了有向无环图。这个图结构不占用上下文——它存在 SQLite 的外键关系里。

4. 一次开发,所有 Agent 可用

提示词

Skill

SciTrace

Claude

每 Agent 写一份

每 Agent 写一份

✅ 同一份 MCP 配置

Cursor

每 Agent 写一份

—

✅ 同一份 MCP 配置

Hermes

每 Agent 写一份

每 Agent 写一份

✅ 同一份 MCP 配置

Codex

每 Agent 写一份

—

✅ 同一份 MCP 配置

MCP 是协议标准。写一次服务器,所有 MCP 兼容 Agent 自动获得推理追踪能力。不需要为每个 Agent 移植提示词。

5. 数据能被程序消费

提示词产生的结构化输出只有 LLM 能读。SciTrace 的数据存在 SQLite 里——任何工具都能读:

Python 分析脚本 → 直接读 SQLite
可视化工具     → scitrace-viz 一键出 HTML
CI/CD 流水线   → sqlite3 命令行查询
Jupyter        → import sqlite3 直接分析

不需要过 LLM——数据的消费者可以是代码。


Related MCP server: Agent Progress Tracker MCP Server

架构

Agent (Claude/Cursor/Hermes/Codex)
    │
    │ MCP 协议 (stdio)
    │
    ▼
┌─────────────────────────┐
│   SciTrace MCP Server   │
│                         │
│  build_trace  ← 写入    │
│  query_trace  ← 读取    │
│                         │
│  ↓ SQLite               │
│  steps 表               │
│  - id, parent_id (DAG)  │
│  - type (6 种推理类型)   │
│  - summary, artifacts   │
└─────────────────────────┘

快速开始

pip install scitrace

在你的 MCP 客户端配置中添加:

{
  "mcpServers": {
    "scitrace": {
      "command": "python",
      "args": ["-m", "scitrace"]
    }
  }
}

Agent 即可调用 build_trace 和 query_trace。

数据存储

项

默认值

覆盖方式

数据库路径

~/.scitrace/traces.db

SCITRACE_DB 环境变量,或 MCP 配置 args 里加 --db <path>

可视化输出目录

当前工作目录

SCITRACE_OUTPUT 环境变量

{
  "mcpServers": {
    "scitrace": {
      "command": "python",
      "args": ["-m", "scitrace", "--db", "/path/to/custom.db"]
    }
  }
}

可视化

pip install 附带 scitrace-viz 命令——把推理链渲染成完全离线的交互式 HTML(自绘 SVG DAG,零外部依赖,内网/断网环境可用):

scitrace-viz                 # 可视化最近一条 trace
scitrace-viz <trace_id>      # 可视化指定 trace
scitrace-viz --out ./viz     # 指定输出目录
scitrace-viz --index         # 生成全部 trace 的概览索引页 index.html
scitrace-viz --theme dark    # 指定初始主题(页面内可随时切换)
  • 悬停节点看完整摘要;点击节点打开详情面板(父/子步骤、artifacts 文件链接)

  • 双击折叠子树;滚轮缩放、拖拽平移、一键适应

  • 明暗主题切换(记忆在 localStorage);含环的推理链自动回退为时间线布局

  • 旧版本(v0.1.x)数据库首次打开时自动迁移,原文件备份为 traces.db.bak-<日期>


让 Agent 真正开始记录

装好 MCP 只是第一步:Agent 不会主动调用 build_trace,除非你在它的配置里告诉它。

规范源:prompts/RULES.md(何时记 / 记什么 / 何时查)。各客户端模板是压缩版,冲突时以 RULES 为准。

客户端

模板文件

放哪里

Claude Desktop

prompts/claude-desktop.md

项目 Instructions / CLAUDE.md

Cursor

prompts/cursor.md

.cursor/rules/scitrace.mdc

Codex CLI

prompts/codex-agents.md

项目根目录 AGENTS.md

Hermes

prompts/hermes.md

系统提示 / skill

硬规则摘要:

  1. 何时记:可验证子任务结束后才 build_trace;走不通必须 backtrack;会话结束前落库

  2. 记什么:trace_id 整任务固定;summary 一行=做了什么+学到什么;parent_id 连成 DAG

  3. 何时查:新会话 / 从失败点续作 / 早期步骤被挤掉时先 query_trace;禁止让用户重讲库里已有历史

  4. 边界:只记录、只查询——不控制推理路径


两个 Tool

build_trace

记录一个推理步骤。Agent 每次完成一个可验证的子任务时调用。

参数

说明

step_id

步骤唯一标识

trace_id

属于哪条推理链

type

hypothesis / analysis / experiment / verification / conclusion / backtrack

summary

一句话概括这步做了什么

parent_id

依赖哪一步(构建 DAG)

artifacts

关联文件路径

query_trace

按条件查询历史推理步骤。

参数

说明

trace_id

按推理链过滤

type

按类型过滤

limit

返回上限(默认 50,最大 1000)


使用示例

一次完整的推理链记录:

build_trace: { "step_id": "h1", "trace_id": "exp-001", "type": "hypothesis", "summary": "假设 P != NP" }
build_trace: { "step_id": "a1", "trace_id": "exp-001", "type": "analysis", "summary": "SAT 是困难的", "parent_id": "h1" }
build_trace: { "step_id": "e1", "trace_id": "exp-001", "type": "experiment", "summary": "运行基准测试", "parent_id": "a1", "artifacts": ["results.csv"] }
build_trace: { "step_id": "c1", "trace_id": "exp-001", "type": "conclusion", "summary": "结论:……", "parent_id": "e1" }

query_trace: { "trace_id": "exp-001" }        → 返回整条链
query_trace: { "type": "experiment" }         → 返回所有实验步骤
query_trace: { "limit": 10 }                  → 最近 10 步

开发

git clone https://github.com/Mobai-read/scitrace
cd scitrace
pip install -e ".[dev]"
pytest

详细贡献流程见 CONTRIBUTING.md。


对比总结

提示词

Skill

SciTrace

数据位置

上下文窗口

上下文窗口

SQLite

跨会话持久化

❌

❌

✅

结构化查询

❌

❌

✅

DAG 依赖

❌

❌

✅ (parent_id)

程序可读

❌

❌

✅ (SQLite)

多 Agent 通用

每 Agent 一份

每 Agent 一份

✅ 一份配置

长链推理

挤爆上下文

挤爆上下文

上下文干净


文档


📣 分享 / 引用

把 SciTrace 推荐给朋友,或嵌入到你的项目里:

在你的 README 里加一个徽章:

[![PyPI](https://img.shields.io/pypi/v/scitrace)](https://pypi.org/project/scitrace/)

任何环境一条命令安装:

pip install scitrace

许可

MIT

Available Tools

2 tools
build_traceA

Record a reasoning step from the agent's execution. Each step has a type (hypothesis/experiment/analysis/conclusion/verification/backtrack), an optional parent_id to build a reasoning DAG, and optional artifact file paths.

Inputs: type (required), step_id (required), summary (required), trace_id (required), +2 more.

query_traceA

Query historical reasoning steps. Filter by trace_id and/or type. Returns steps ordered by most recent first, up to the specified limit.

Inputs: type, limit, trace_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 2 tools

    Disambiguation5/5

    build_trace records a new reasoning step, while query_trace retrieves existing steps. Their purposes are clearly distinct, with no overlap in functionality.

    Naming Consistency5/5

    Both tools follow the consistent verb_noun pattern (build_trace, query_trace), making their actions predictable and easily understood.

    Tool Count3/5

    With only 2 tools, the set is minimal, but each tool is essential for the server's stated purpose of recording and querying reasoning traces. This falls at the borderline of being too thin.

    Completeness4/5

    The server covers the core write (build_trace) and read (query_trace) operations for reasoning traces. Missing update/delete functionality is a minor gap, but acceptable for an append-only trace logging context.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to track, search, and retrieve their progress across projects with persistent memory using SQLite storage and LLM-powered summarization. Supports logging completed work, searching previous entries, and retrieving context for multi-step or multi-agent workflows.
      26 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to persist and retrieve structured thinking graphs using SQLite-backed memory with support for CRUD operations, graph search, and path finding.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Gives AI coding agents persistent memory by storing observations, decisions, and learnings in a local SQLite database with vector search, full-text search, and a rules engine.
      4
      MIT