Universal Source Management System

通用文献管理系统

一个轻量级 FastMCP 服务，用于在本地 SQLite 数据库中管理文献、笔记、实体链接和阅读列表资源。

当前范围

此仓库提供：

• 基于本地 SQLite 的文献管理
• 附加到文献的笔记
• 文献与命名概念之间的实体链接
• 只读数据库检查工具
• 用于查询文献和阅读列表的 MCP 资源
• 规范化标识符存储，并保留过渡期 JSON 缓存

它不集成 MCP Memory Server 或外部记忆图谱。

快速开始

1. 根据当前架构创建数据库：

sqlite3 sources.db < create_sources_db.sql

2. 使用数据库路径安装 FastMCP 服务：

fastmcp install sqlite-paper-fastmcp-server.py --name "Source Manager" -e SQLITE_DB_PATH=/path/to/sources.db

3. 可选：使用仓库中已提交的演示数据 examples/sources.db。

Docker

此服务可以打包为容器化的 stdio MCP 服务。

构建镜像：

docker build -t sqlite-lit-mcp .

使用持久化 SQLite 卷运行：

mkdir -p data
docker run --rm -i \
  -e SQLITE_DB_PATH=/data/sources.db \
  -v "$(pwd)/data:/data" \
  sqlite-lit-mcp

注意：

• 镜像默认将 SQLITE_DB_PATH 设置为 /data/sources.db。
• 如果数据库文件不存在，容器会使用 create_sources_db.sql 初始化数据库。
• 如果挂载的是旧版数据库，请先应用 migrations/ 下所需的迁移，再启动服务。
• 此仓库以 stdio MCP 服务的形式运行，因此默认无需开放 HTTP 端口。

使用 Docker Compose：

docker compose run --rm sqlite-lit-mcp

当前工具概览

已实现的工具：

• read_query
• list_tables
• describe_table
• get_table_stats
• get_database_info
• vacuum_database
• add_sources
• add_notes
• update_status
• add_identifiers
• link_to_entities
• get_source_entities
• update_entity_links
• remove_entity_links
• get_entity_sources

已实现的资源：

• source://<id>
• source://by-identifier/<type>/<value>
• reading-list://unread
• reading-list://reading
• entity://<entity_name>

架构说明

当前架构以四张表为核心：

• sources
• source_identifiers
• source_notes
• source_entity_links

sources.identifiers 仍作为过渡期 JSON 缓存保留，但现在通过 source_identifiers 查询标识符。

支持的标识符类型：

• semantic_scholar
• doi
• arxiv
• openalex
• pmid
• isbn
• url

支持的实体关系类型：

• discusses
• introduces
• extends
• evaluates
• applies
• critiques
• supports
• contradicts
• refutes

轻量级溯源字段位于 sources 表中：

• provider
• discovered_via
• discovered_at

架构现在使用 PRAGMA user_version = 3。

迁移

如果你有版本 0 或版本 1 的数据库，请应用：

sqlite3 /path/to/sources.db < migrations/2026-03-09__normalize-identifiers.sql
sqlite3 /path/to/sources.db < migrations/2026-03-09__expand-entity-relation-types.sql

如果你已迁移到版本 2，请应用：

sqlite3 /path/to/sources.db < migrations/2026-03-09__expand-entity-relation-types.sql

这些迁移会：

• 添加 source_identifiers
• 从旧版 JSON 列回填标识符行
• 添加溯源字段
• 扩展 source_entity_links.relation_type，加入 supports、contradicts 和 refutes
• 将 PRAGMA user_version 更新为 3

服务会在连接时检查 PRAGMA user_version，并拒绝连接尚未迁移的旧版数据库。

软件包布局

实现代码位于 sqlite_lit_server/ 下：

• app.py 创建 FastMCP 实例并注册工具和资源
• db.py 负责连接设置和架构版本检查
• repository.py 将涉及大量 SQL 的查询逻辑放在数据层附近
• tools_admin.py、tools_sources.py 和 tools_entities.py 存放 MCP 工具
• resources.py 定义 MCP 资源

sqlite-paper-fastmcp-server.py 仍作为精简的兼容性垫片保留。

批量导入来源

add_sources 是新来源的批量导入入口。它接受一个名为 sources 的参数，其中每项为：

[title, source_type, identifier_type, identifier_value, initial_note]

initial_note 必须为 null，或包含 title 和 content 的对象。

支持的 source_type 值：

• paper
• webpage
• book
• video
• blog

支持的 identifier_type 值：

• semantic_scholar
• doi
• arxiv
• openalex
• pmid
• isbn
• url

重复项处理：

• 标识符完全匹配时，将返回 Source already exists，并附带已有来源的负载。
• 基于标题的模糊匹配会返回 Potential duplicates found. Please verify or use add_identifiers if these are the same source.
• 批量写入成功时，会按请求中各项的顺序为每项返回一个结果。

MCP/JSON 负载示例：

{
  "sources": [
    [
      "Attention Is All You Need",
      "paper",
      "arxiv",
      "1706.03762",
      {
        "title": "Initial thoughts",
        "content": "Transformers start here."
      }
    ],
    [
      "OpenAlex Import",
      "paper",
      "openalex",
      "W1234567890",
      null
    ]
  ]
}

Python 调用示例：

add_sources([
    (
        "Attention Is All You Need",
        "paper",
        "arxiv",
        "1706.03762",
        {
            "title": "Initial thoughts",
            "content": "Transformers start here.",
        },
    ),
    (
        "OpenAlex Import",
        "paper",
        "openalex",
        "W1234567890",
        None,
    ),
])

无论在本地启动服务，还是通过 Docker 使用 docker compose run --rm sqlite-lit-mcp 启动，这些工具负载都适用。

批量写入约定

复数形式的写入工具接受列表，并按输入顺序返回逐项结果列表。相关批量工具包括：

• add_notes
• add_identifiers
• update_status
• link_to_entities

使用示例

添加另一个标识符：

add_identifiers([
    (
        "Attention Is All You Need",
        "paper",
        "arxiv",
        "1706.03762",
        "semantic_scholar",
        "204e3073870fae3d05bcbc2f6a8e263d9b72e776",
    ),
])

读取来源资源：

source://by-identifier/arxiv/1706.03762