Corpuscribe

Let your literature inform your language

How do researchers express uncertainty? Is a formulation common across several papers, or repeated in just one? What wording accompanies a particular kind of estimate?

Corpuscribe brings those questions into your AI writing workflow. Its local MCP server searches a prepared literature database, compares formulations, and returns sentences with their article and page references. Your writing assistant uses those examples to suggest revisions you can inspect.

Early release · v0.1. Three read-only tools are available today. PDF ingestion, paragraph revision and automatic classification are outside this server's current scope.

Related MCP server: ares-mcp

From literature to a revision

flowchart LR
    A[Prepared literature corpus] --> B[(Local SQLite database)]
    J[Optional Jev classifications] --> B
    B --> C[Corpuscribe MCP]
    C --> D[Your writing assistant]
    D --> E[Revision with sourced examples]
    classDef paper fill:#F4F0E8,stroke:#182C32,color:#182C32
    classDef accent fill:#182C32,stroke:#182C32,color:#ffffff
    class A,B,J,D,E paper
    class C accent

The server queries saved data. It makes no model calls and requires no API key. An optional upstream classifier can attach rhetorical labels before you search.

Quick start

Use Node.js 22 or newer for the documented setup. The repository's CI tests Node.js 22.

git clone https://github.com/tofunori/corpuscribe.git
cd corpuscribe
npm ci
npm run build

Point the server at an existing compatible database, or try the included fictional two-sentence corpus with Python 3:

python3 - <<'PY'
import sqlite3
from pathlib import Path
path = Path('data/demo.sqlite')
path.parent.mkdir(exist_ok=True)
if path.exists():
    raise SystemExit('Demo database already exists; use it without recreating it.')
with sqlite3.connect(path) as db:
    db.executescript(Path('examples/demo.sql').read_text())
PY
node dist/server.js --database "$PWD/data/demo.sqlite"

The server uses stdio: it waits for an MCP client rather than opening a webpage or an interactive terminal prompt.

Connect your assistant

Add this entry to a client that accepts an mcpServers configuration, replacing the two paths with absolute paths on your machine:

{
  "mcpServers": {
    "corpuscribe": {
      "command": "node",
      "args": [
        "/absolute/path/to/corpuscribe/dist/server.js",
        "--database",
        "/absolute/path/to/linguistic.sqlite"
      ]
    }
  }
}

You can alternatively supply the database path through CORPUSCRIBE_DB. The server does not automatically load .env files. Client configuration formats vary; the JSON above is a configuration example, not an automatic installer.

Three tools, one corpus

Find cautious language

Call corpus_search with:

{
  "query": "underestimate",
  "limit": 5,
  "rhetoricalFilters": [
    { "label": "certainty", "choice": "possible", "minProbability": 0.9 }
  ]
}

The fictional demo corpus returns this sentence inside the tool's result:

{
  "id": "demo-1",
  "article": "demo:paper-a",
  "title": "Fictional snow study",
  "pagePdf": 4,
  "sourceId": "demo:source-a",
  "text": "These assumptions may underestimate melt.",
  "wordCount": 6
}

In a writing session, try: “Find examples of ‘may underestimate’, show their sources, and use them to suggest a cautious revision of my sentence.” The assistant proposes the revision; Corpuscribe supplies the examples.

Read the counts correctly

• Search is case-insensitive substring matching, not semantic retrieval or whole-word matching. PDF line breaks can affect phrase matches.

• occurrences currently counts matching sentences, not individual repetitions of a term.

• Article counts help distinguish broad usage from repeated wording in one source. Source duplication depends on the upstream database.

• A common expression is evidence of usage, not proof of scientific correctness or a universal style rule.

• Jev labels are optional, probabilistic and dependent on upstream coverage. This version does not select a classifier schema: use an index containing one intended schema to avoid mixing label versions.

See the database contract for required columns and coverage definitions.

Your corpus stays under your control

The SQLite connection is read-only. The repository contains code and fictional examples; personal databases, PDFs and environment files are ignored by Git.

Retrieved sentences are returned to your MCP client. If that client uses a hosted model, the excerpts it includes in its prompts may be sent to that provider. Choose a client appropriate for your corpus.

Development

npm test
npm run check
npm run build

Tests use a synthetic SQLite fixture. See Contributing for reporting problems and proposing changes.

Next directions

• Linguistic feature queries for verbs, adverbs and connectors.

• Richer classification provenance and schema selection.

• Corpus-aware paragraph diagnostics.

• Easier corpus preparation and onboarding.

These are planned directions, not tools available in v0.1.