grammar-kb-mcp
这是一个英语语法知识库的 MCP 查询服务,可检索和浏览已导入的讲义、知识点、标志词及关系。
按关键词(中文/英文)检索语法知识点,可按分类筛选并限制返回条数。
按 id 获取单个知识点的完整 Markdown(解释、例句、表格、溯源)。
按讲号获取整讲 Markdown 讲义(标题、正文、GFM 表格)。
列出全部已导入讲次(讲号、标题、分类)。
列出标志词/关键词,可按分类或具体时态限定。
按关系类型(如“主将从现”“时态呼应”)查找知识点。
查看知识库统计(讲次/知识点/标志词数量及类别分布)。
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grammar-kb-mcp search for "since" in tense category"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
/docsinteractive 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 |
| fitz extracts spans (font/position/direction) → filters watermarks → reorders lines; pdfplumber restores tables on the filtered characters |
| line classification (section/subsection/sub-item/example/exercise) → knowledge-point splitting |
| classification rules, keyword dictionary, relation detection, exam signals (pure functions) |
| corpus-based word list (definition/part of speech/inflection) |
| tables → GFM, rendering of knowledge points and full lectures |
| schema + CRUD + FTS5(trigram, external-content), no truncation |
| call-oriented query API |
| PDF → database (directory import = full rebuild, reproducible ids) |
| separate SQLite store for homework scores (CRUD; defaults to iCloud Drive) |
| command line |
| HTTP service (optional extra) |
| MCP service (optional extra) |
| learning frontend (Vite, see "Web Learning Frontend" below and |
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_FONTSinpdf_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_RULESinclassify.py: maps topic categories by title keywords.Keyword dictionary —
TENSE_MARKERSinclassify.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 8000After starting, visit http://127.0.0.1:8000/docs to view the interactive API documentation. Endpoints:
Method | Path | Description |
GET |
| Statistics and dataset metadata |
GET |
| Lecture list |
GET |
| Lecture content (with tables restored) |
GET |
| A knowledge point |
GET |
| Full-text search |
GET |
| Marker words |
GET |
| Query by relation |
GET |
| All exam-signal dimensions |
GET |
| Reverse lookup of knowledge points by exam signal |
GET |
| Word list (definition/part of speech/inflection) |
GET |
| Knowledge-point topic tree (category → topic) |
GET |
| Look up any word (ECDICT full dictionary) |
GET/POST |
| Homework scores: list / add |
PUT/DELETE |
| 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:
The
GRAMMAR_KB_EXAM_DBenvironment variableiCloud 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 iCloudFallback
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-mcpExposed 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:5180Features:
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 toolsfind_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Query, explore, and manage your databases through natural conversation.
A search engine that learns from your grades. Store text, records, images or embeddings.
YouTube transcripts (chunks, phrase search, most replayed moments), PDFs and web pages as Markdown.
Query and audit AppSheet apps in natural language via Knotrik's pre-scanned definitions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityDmaintenanceEnables 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.6MIT
- FlicenseCqualityBmaintenanceEnables 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-
- FlicenseAqualityCmaintenanceEnables 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.51-