Skip to main content
Glama
Mobai-read

SciTrace MCP Server

by Mobai-read
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesReasoning step type
step_idYesUnique identifier for this step
summaryYesOne-line summary of what this step did
trace_idYesIdentifier for the overall trace/experiment
artifactsNoOptional list of associated file paths
parent_idNoOptional parent step ID for DAG construction

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool 'records' a step but does not disclose side effects such as whether the step is appended, overwritten, persisted immediately, or whether an existing trace is required. It also omits any mention of return values or failure modes, providing minimal insight beyond the input schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no filler content. It front-loads the core action ('Record a reasoning step') and then efficiently summarizes the optional fields, making it appropriately sized and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers the tool's write behavior and input structure for basic use, but it leaves gaps regarding the lifecycle of a trace (e.g., whether the trace must already exist) and the relationship to the sibling query_trace. No output schema exists, so the description should provide more context about what happens after recording, which it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides descriptions for all six parameters, achieving 100% coverage. The description adds some context by mentioning that parent_id builds a reasoning DAG and artifacts are file paths, but these largely mirror the schema descriptions. Since the schema handles the parameter semantics well, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Record' with the resource 'a reasoning step from the agent's execution', and explicitly enumerates the step types and structural elements (parent_id, artifacts). This clearly differentiates it from the sibling query_trace, which is a read-oriented tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives context ('from the agent's execution') implying when the tool should be used, but it lacks explicit 'when not to use' guidance or any mention of the sibling query_trace as an alternative. No exclusions or prerequisites are stated, so the usage guidance is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoFilter by step type
limitNoMax steps to return (default 50)
trace_idNoFilter by trace identifier

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behaviors: results are ordered by most recent first and limited by the limit parameter. However, it does not explicitly state that the operation is read-only or that no modifications occur, and there are no annotations to fall back on. The description gives basic insight but not comprehensive disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences, each serving a clear purpose: purpose, filters, and result behavior. No unnecessary words or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a query tool with three optional parameters and no output schema, the description covers the purpose, filtering options, ordering, and limit. It lacks explicit information about response format or state effects, but given the simplicity, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage with clear descriptions of each parameter. The description adds the nuance that filters can be combined ('and/or') and reiterates the limit behavior, but does not introduce new semantic meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Query' with resource 'historical reasoning steps', clearly stating the operation. It also distinguishes from sibling 'build_trace' by implying a retrieval vs creation distinction, so purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for querying but does not explicitly state when to use this tool versus 'build_trace' or any alternative. The intent is implied by the verb 'query' and the mention of 'historical steps', but no explicit guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedbuild_trace
    • First observedquery_trace
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Agent Progress Tracker MCP

    thesammykins
    A
    license
    Not graded
    quality
    C
    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.
    4 npm
    MIT

  • thoughtgraph-mcp

    xlisp
    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
    -

  • code-recall

    AbianS
    A
    license
    Not graded
    quality
    C
    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