Skip to main content
Glama
grammar-kb-mcp

grammar-kb-mcp

grammar-kb

A monorepo for English grammar teaching handouts — knowledge base + learning frontend — in two layers:

  • grammar_kb/ (Python backend): cleans and structures PDF textbooks/handouts into a searchable, traceable knowledge-point database — automatically removes watermarks, restores tables, splits knowledge points, extracts keywords and relations, stores them in local SQLite (FTS5 full-text search), and provides CLI, HTTP API, and MCP services.

  • web/ (Vite frontend): a student-facing learning interface — browse handouts by course / vocabulary / knowledge system, plus homework score records (CRUD, persisted on iCloud Drive, synced across devices).

Works with any teaching/technical PDF that has a "relatively uniform layout, header/footer watermarks, and tables".

Features

  • 🧹 Watermark removal: removes header/footer/slanted background watermarks by font + text direction (including PDF subset font prefixes)

  • 📊 Table restoration: automatically detects ruled tables and restores them as GFM Markdown tables

  • 🧩 Knowledge-point splitting: splits into independently searchable units by heading level (chapter/section/subsection/sub-item/example sentence/exercise)

  • 🏷️ Classification & relations: classifies by topic, extracts keywords/marker words and relations between knowledge points (e.g. "main-clause future, subordinate-clause present", "sequence of tenses")

  • 🎯 Exam signals: each knowledge point is tagged with exam dimensions (tense/voice/spelling/subordinate clause…), and supports "reverse lookup of knowledge points by exam signal"

  • 📖 Word list: generates a word list from the handout corpus (definition/part of speech/inflection/source traceability)

  • 🔍 Traceable: each knowledge point carries 讲次 · 节路径 · 页码 and can be located back to the original text

  • 🗄️ No truncation: body text is stored in SQLite TEXT (no length limit); FTS is used only for matching

  • 🌐 HTTP API: built-in REST service (FastAPI, with /docs interactive documentation)

  • 🔌 MCP ready: built-in MCP service; clients like Claude can query directly

Related MCP server: PDF RAG MCP Server

Quick Start

uv sync                          # 安装依赖(含开发依赖)
uv run grammar-kb ingest ./pdfs  # 导入一个 PDF 目录(全量重建,id 可复现)
uv run grammar-kb stats          # 查看统计

Haven't installed uv? Run curl -LsSf https://astral.sh/uv/install.sh | sh

Common Commands

uv run grammar-kb ingest ./pdfs               # 导入目录(或单个 PDF 文件)
uv run grammar-kb lecture 25                   # 输出某讲的完整 Markdown(表格已还原)
uv run grammar-kb lecture 25 --format html     # 输出某讲的 HTML(表格渲染为 <table>)
uv run grammar-kb kp 173                       # 输出某知识点的完整 Markdown
uv run grammar-kb search "关键词"              # 全文检索知识点
uv run grammar-kb search "since" --category 时态
uv run grammar-kb markers --category 时态      # 列出某类下所有关键词/标志词
uv run grammar-kb markers --tense 现在完成时   # 列出某时态的标志词
uv run grammar-kb relation 主将从现            # 按关系类型查知识点
uv run grammar-kb exam-signal 从句             # 按考点信号反查知识点(反之亦然)
uv run grammar-kb exam-signal --list           # 列出所有考点信号维度
uv run grammar-kb words --limit 100            # 单词表(释义/词性/词形变化/来源)
uv run grammar-kb stats                        # 统计
uv run grammar-kb serve --port 8000            # 启动 HTTP 查询服务(见 http://127.0.0.1:8000/docs)

The default database is data/grammar.db in the run directory; you can override it with --db or the GRAMMAR_KB_DB environment variable.

Use a Prebuilt Dataset Directly (Optional)

If you don't want to ingest it yourself, download the matching grammar.db from GitHub Releases, place it at data/grammar.db (or specify a path with GRAMMAR_KB_DB) and query directly. The dataset version is indicated by the release tag (e.g. data-v1); the meta table in the database also records the version and generation time.

Architecture

PDF ──► pdf_parser   去水印(字体+方向过滤)+ 重排行 + 还原表格
      └─► structure    文本 → 大纲树 → 知识点切分(分类 + 关键词 + 关系)
                      └─► db          SQLite(lecture / knowledge_point / marker / relation / block + FTS5)
                                      └─► query  查询 API(CLI 与 MCP 共用)

Module

Responsibility

pdf_parser.py

fitz extracts spans (font/position/direction) → filters watermarks → reorders lines; pdfplumber restores tables on the filtered characters

structure.py

line classification (section/subsection/sub-item/example/exercise) → knowledge-point splitting

classify.py

classification rules, keyword dictionary, relation detection, exam signals (pure functions)

vocabulary.py

corpus-based word list (definition/part of speech/inflection)

markdown.py

tables → GFM, rendering of knowledge points and full lectures

db.py

schema + CRUD + FTS5(trigram, external-content), no truncation

query.py

call-oriented query API

ingest.py

PDF → database (directory import = full rebuild, reproducible ids)

exam_store.py

separate SQLite store for homework scores (CRUD; defaults to iCloud Drive)

cli.py

command line

server.py

HTTP service (optional extra)

mcp_server.py

MCP service (optional extra)

web/

learning frontend (Vite, see "Web Learning Frontend" below and web/README.md)


Database Schema (Summary)

lecture(number UNIQUE, title, full_title, category, subcategory, source_file, page_count)
knowledge_point(lecture_id, lecture_number, title, category, section_path,
                body_md, examples_md, table_md, is_table, source_page, source_bbox, tags_json, ord)
marker(kp_id, lecture_number, marker, marker_type, tense, note)        -- 关键词/标志词
relation(kp_id, type, to_kp_id, note)                                  -- 关系:主将从现/时态呼应…
lecture_block(lecture_id, page, seq, kind, text_md)                    -- 整讲还原用

-- 全文检索(external-content + trigram,中文子串命中)
CREATE VIRTUAL TABLE kp_fts USING fts5(title, body_md, examples_md, table_md,
    content='knowledge_point', content_rowid='id', tokenize='trigram');

Customize Your Dataset

The tool is tuned by default for "uniformly formatted teaching handouts". When switching datasets, you usually only need to change three places (all in grammar_kb/):

  • Watermark fonts — WATERMARK_FONTS in pdf_parser.py: add your header/watermark font names. Quick script to diagnose fonts in a new PDF:

    uv run python -c "import fitz; d=fitz.open('某.pdf'); \
    import collections; c=collections.Counter(s['font'] for b in d[0].get_text('dict')['blocks'] if b.get('type',0)==0 for l in b['lines'] for s in l['spans'] if s['text'].strip()); print(c)"
  • Classification rules — _TITLE_RULES in classify.py: maps topic categories by title keywords.

  • Keyword dictionary — TENSE_MARKERS in classify.py (or a custom dictionary of the same kind).

  • Layout regexes — structure.py: if your heading levels use different markers (e.g. 一、 / (一)), adjust the corresponding regexes.

As an HTTP Service

uv sync --extra server                       # 安装 server 依赖(fastapi + uvicorn)
uv run grammar-kb serve --port 8000          # 经由 CLI
# 或独立入口:
uv run grammar-kb-server --host 0.0.0.0 --port 8000

After starting, visit http://127.0.0.1:8000/docs to view the interactive API documentation. Endpoints:

Method

Path

Description

GET

/stats

Statistics and dataset metadata

GET

/lectures

Lecture list

GET

/lectures/{number}?format=markdown|html

Lecture content (with tables restored)

GET

/kp/{id}?format=markdown|html

A knowledge point

GET

/search?q=...&category=...&limit=...

Full-text search

GET

/markers?category=时态&tense=...

Marker words

GET

/relation?type=主将从现

Query by relation

GET

/exam-signals

All exam-signal dimensions

GET

/exam-signal?signal=时态

Reverse lookup of knowledge points by exam signal

GET

/vocabulary?limit=300&min_freq=2

Word list (definition/part of speech/inflection)

GET

/taxonomy

Knowledge-point topic tree (category → topic)

GET

/dict/{word}

Look up any word (ECDICT full dictionary)

GET/POST

/exams

Homework scores: list / add

PUT/DELETE

/exams/{id}

Homework scores: update / delete

Where Homework Score Data Is Stored

Scores are stored in a separate SQLite database (separate from the handout database data/grammar.db); the path is resolved in order:

  1. The GRAMMAR_KB_EXAM_DB environment variable

  2. iCloud Drive: ~/Library/Mobile Documents/com~apple~CloudDocs/grammar-kb/exam.db (when on macOS and iCloud is available) — the data is small, so it lives in the cloud and is synced across devices by iCloud

  3. Fallback data/exam.db

The database deliberately does not use WAL mode (a single self-contained file is more reliable for iCloud whole-file sync); after setting up this repo on another device and signing into the same iCloud account, starting the service reads the same scores.

Example:

curl "http://127.0.0.1:8000/search?q=现在完成时&limit=3"
curl "http://127.0.0.1:8000/lectures/25?format=html"

Unified response format: all endpoints return {code, message, data}.

// 成功(HTTP 200)
{ "code": 0, "message": "ok", "data": { "knowledge_points": 359, ... } }
// 错误(HTTP 与 code 一致)
{ "code": 404, "message": "第 99 讲不存在", "data": null }

CORS: all origins are allowed by default (Access-Control-Allow-Origin: *), so the frontend can make cross-origin calls directly. To tighten the whitelist: GRAMMAR_KB_CORS_ORIGINS=https://a.com,https://b.com grammar-kb-server.

As an MCP Service

uv sync --extra mcp
uv run grammar-kb-mcp

Exposed tools: search_knowledge_points, get_knowledge_point, get_lecture_markdown, list_lectures, list_markers, find_by_relation, stats. Each tool is a thin wrapper around Query.

Example Claude Desktop configuration:

{
  "mcpServers": {
    "grammar-kb": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/grammar-kb", "grammar-kb-mcp"],
      "env": { "GRAMMAR_KB_DB": "/path/to/grammar-kb/data/grammar.db" }
    }
  }
}

Web Learning Frontend (web/)

A student-facing learning interface that depends on a locally running backend service (default http://127.0.0.1:8000``; during development, Vite proxies /api/*` to it).

# 终端 1:先起后端
uv sync --extra server && uv run grammar-kb-server

# 终端 2:再起前端
cd web && npm install && npm run dev     # http://localhost:5180

Features:

  • Browse by course: 48 lectures grouped by grammar system (morphology/tense/voice/non-finite verbs/syntax/comprehensive review); click to view the full lecture

  • Vocabulary: 600+ high-frequency words (definition/part of speech/inflection/source in handouts), filter by part of speech, search, sort

  • Knowledge system: 359 scattered knowledge points aggregated into a two-level tree of "grammar category → topic", with a fixed-collocation quick-reference table

  • 🎯 Exam signals (bidirectional): bidirectional jumps between knowledge points ↔ marker words/tenses — "seeing this word tells you which knowledge points are being tested"

  • 📝 Homework scores: one homework sheet per lecture (35 questions, full score 100). Click a question number to mark right/wrong, and the score is calculated automatically; all attempts are kept, editable and deletable; the mistake notebook aggregates error counts by "lecture + question number"; data is stored to iCloud via the backend /exams (see above), survives across browsers/devices, and old localStorage records are automatically migrated on first open

Tech stack: Vite + native ES Modules · marked (Markdown rendering), no framework dependencies. See web/README.md for more details.

Testing

uv run pytest                           # 全部(含真实 PDF 集成)
uv run pytest -m "not integration"      # 仅纯单测(无需 PDF,秒级)

Coverage: watermark filtering / line reordering / table restoration / knowledge-point splitting / classification / keyword extraction / DB no-truncation round-trip / FTS Chinese-English search / cascade cleanup / reproducible id rebuild / querying / end-to-end integration.

Integration tests require a PDF directory, specified via the GRAMMAR_TEST_PDF_DIR environment variable; if it is not set or does not exist, they are skipped automatically.

Design Trade-offs and Known Limitations

  • Borderless tables: only ruled tables that pdfplumber can detect via borders are restored; a few borderless multi-column comparisons are kept as body paragraphs (no information is lost). A fallback detection based on "column whitespace alignment" can be added later.

  • Knowledge-point splitting: heuristic based on uniform layout; unusual layouts may merge/split slightly differently, and you can double-check with search + kp.

  • Directory import rebuilds: ingest <目录> clears and rebuilds the database (ids start at 1 and are reproducible); importing a single PDF only updates that lecture.

Available Tools

7 tools
find_by_relationB

按关系类型查知识点,如 relation_type="主将从现"、"时态呼应"。

Inputs: relation_type (required). Returns: result

get_knowledge_pointA

按 id 获取单个知识点的完整 markdown(含解释、例句、表格、溯源)。

Inputs: kp_id (required). Returns: result

get_lecture_markdownB

获取某讲的完整 markdown 讲义(标题/正文/表格已还原为 GFM)。

例如 number=25 返回"第二十五讲 动词时态3"的完整 md。

Inputs: number (required). Returns: result

list_lecturesA

列出已导入的全部讲次(讲号、标题、分类)。

Inputs: no named parameters. Returns: result

list_markersA

列出标志词/关键词,可溯源到讲次。

默认返回所有时态关键词(category="时态")。 可用 tense 限定具体时态,如 tense="现在完成时"。

Inputs: tense, category. Returns: result

search_knowledge_pointsB

按关键词检索语法知识点。

参数: query: 关键词(中文或英文,如 "现在完成时"、"主将从现"、"since")。 category: 可选,限定大类:词法/句法/时态/语态/非谓语/综合复习。 limit: 最多返回条数。 返回:知识点列表(标题、所在讲次、分类、标签)。

Inputs: query (required), limit, category. Returns: result

statsC

返回知识库统计(讲次/知识点/标志词数量,按类别分布)。

Inputs: no named parameters. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct retrieval purpose: search, get by id, get lecture markdown, list lectures, list markers, find by relation, and stats. Overlap between search_knowledge_points and list_markers is minimal because markers are a specific entity type with their own filters.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (search_, get_, list_, find_by_). 'stats' is a minor deviation as a bare noun, but the overall naming remains predictable and readable.

    Tool Count5/5

    7 tools is well-scoped for a knowledge base retrieval server. Each tool serves a clear function without redundancy, fitting comfortably within the ideal 3-15 range.

    Completeness4/5

    Core retrieval operations are covered: search, get by id, get lecture, list lectures, list markers, find by relation, and stats. Minor gaps exist, such as no direct way to list all knowledge points without a search term or to filter markers by lecture, but agents can work around these.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables storage and retrieval of knowledge in a graph database format, allowing users to create, update, search, and delete entities and relationships in a Neo4j-powered knowledge graph through natural language.
      5
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables intelligent search and question-answering over PDF documents using semantic similarity and keyword search. Supports OCR for scanned PDFs, persistent vector storage with ChromaDB, and maintains source tracking with page numbers.
      6
      MIT
    • F
      license
      C
      quality
      B
      maintenance
      Enables academic literature management through PDF import, hybrid search, knowledge graph construction, and automated literature review generation. Combines full-text search with semantic vector search for comprehensive paper analysis.
      55
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables natural-language querying of course, teacher, and assignment information stored in a SQLite database, including fuzzy course search, teacher lookups, weekly schedules, and assignment deadlines.
      5
      1
      -