Universal Source Management System

A lightweight FastMCP server for managing literature, notes, entity links, and reading-list resources in a local SQLite database.

Current Scope

This repository provides:

- Local SQLite-backed source management
- Notes attached to sources
- Entity links between sources and named concepts
- Read-only database inspection tools
- MCP resources for source lookup and reading lists
- Normalized identifier storage with a transitional JSON cache

It does not integrate with MCP Memory Server or an external memory graph.

Quick Start

1. Create a database from the current schema:

sqlite3 sources.db < create_sources_db.sql

2. Install the FastMCP server with your database path:

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

3. Optional: use the checked-in demo fixture at examples/sources.db.

Docker

This server can be packaged as a containerized stdio MCP server.

Build the image:

docker build -t sqlite-lit-mcp .

Run it with a persistent SQLite volume:

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

Notes:

- The image defaults SQLITE_DB_PATH to /data/sources.db.
- If the database file does not exist, the container initializes it from create_sources_db.sql.
- If you are mounting an older database, apply the required migrations under migrations/ before starting the server.
- This repo runs as a stdio MCP server, so there is no HTTP port to expose by default.

With Docker Compose:

docker compose run --rm sqlite-lit-mcp

Current Tool Surface

Implemented tools:

- 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

Implemented resources:

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

Schema Notes

The current schema centers on four tables:

- sources
- source_identifiers
- source_notes
- source_entity_links

sources.identifiers is still kept as a transitional JSON cache, but identifier lookups now use source_identifiers.

Supported identifier types:

- semantic_scholar
- doi
- arxiv
- openalex
- pmid
- isbn
- url

Supported entity relation types:

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

Lightweight provenance fields live on sources:

- provider
- discovered_via
- discovered_at

The schema now uses PRAGMA user_version = 3.

Migration

If you have a version 0 or version 1 database, apply:

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

If you already migrated to version 2, apply:

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

These migrations:

- adds source_identifiers
- backfills identifier rows from the legacy JSON column
- adds provenance fields
- expands source_entity_links.relation_type to include supports, contradicts, and refutes
- updates PRAGMA user_version to 3

The server checks PRAGMA user_version on connection and will reject older databases until they are migrated.

Package Layout

The implementation is organized under sqlite_lit_server/:

- app.py creates the FastMCP instance and registers tools/resources
- db.py owns connection setup and schema-version checks
- repository.py keeps SQL-heavy lookup logic close to the data layer
- tools_admin.py, tools_sources.py, and tools_entities.py hold the MCP tools
- resources.py defines the MCP resources

sqlite-paper-fastmcp-server.py remains as a thin compatibility shim.

Batch Import Sources

add_sources is the batch import entrypoint for new sources. It accepts one argument named sources, where each item is:

[title, source_type, identifier_type, identifier_value, initial_note]

initial_note must be either null or an object with both title and content.

Supported source_type values:

- paper
- webpage
- book
- video
- blog

Supported identifier_type values:

- semantic_scholar
- doi
- arxiv
- openalex
- pmid
- isbn
- url

Duplicate handling:

- Exact identifier matches return Source already exists together with the existing source payload.
- Title-based fuzzy matches return Potential duplicates found. Please verify or use add_identifiers if these are the same source.
- Successful batch writes return one result per input item in the same order as the request.

Example MCP/JSON payload:

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

Example Python call:

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

The same tool payloads work whether you start the server locally or through Docker with docker compose run --rm sqlite-lit-mcp.

Batch Write Conventions

Plural write tools accept lists and return a per-input result list in the same order. Related batch tools include:

- add_notes
- add_identifiers
- update_status
- link_to_entities

Example Usage

Add another identifier:

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

Read a source resource:

source://by-identifier/arxiv/1706.03762