grammar-kb-mcp
grammar-kb
Wissensdatenbank + Lern-Frontend für englische Grammatik-Lehrmaterialien – ein Monorepo mit zwei Ebenen:
grammar_kb/(Python-Backend): Bereinigt und strukturiert PDF-Lehrbücher/-Skripte zu einer durchsuchbaren, rückverfolgbaren Wissensdatenbank – entfernt automatisch Wasserzeichen, rekonstruiert Tabellen, segmentiert Wissenspunkte, extrahiert Schlüsselwörter und Beziehungen, speichert in lokaler SQLite (FTS5-Volltextsuche), bietet CLI, HTTP-API und MCP-Dienst.web/(Vite-Frontend): Lernoberfläche für Studierende – durchsucht Skripte nach Kurs / Vokabelliste / Wissenssystem, plus Notenverwaltung für Hausaufgaben (CRUD, persistiert in iCloud Drive, geräteübergreifend synchronisiert).
Geeignet für jedes Lehr-/Technik-PDF mit „relativ einheitlichem Layout, Kopf-/Fußzeilen-Wasserzeichen und Tabellen".
Funktionen
🧹 Wasserzeichenentfernung: Entfernt Kopf-/Fußzeilen und schräg gesetzte Hintergrundwasserzeichen anhand von Schriftart + Textrichtung (inkl. PDF-Subset-Schriftpräfixen)
📊 Tabellenrekonstruktion: Erkennt automatisch Tabellen mit Rahmenlinien und rekonstruiert sie als GFM-Markdown-Tabellen
🧩 Wissenspunkt-Segmentierung: Zerlegt nach Überschriftenebenen (Kapitel/Abschnitt/Unterabschnitt/Unterpunkt/Beispielsatz/Übung) in unabhängig durchsuchbare Einheiten
🏷️ Klassifikation & Beziehungen: Klassifiziert nach Thema, extrahiert Schlüsselwörter/Signalmarker und Beziehungen zwischen Wissenspunkten (z. B. „Hauptsatz Futur, Nebensatz Präsens", „Tempuskongruenz")
🎯 Prüfungssignale: Jeder Wissenspunkt wird mit Prüfungsdimensionen markiert (Tempus/Diathese/Rechtschreibung/Nebensätze …), unterstützt „Wissenspunkte anhand von Prüfungssignalen rückwärts suchen"
📖 Vokabelliste: Generiert Vokabelliste aus dem Skript-Korpus (Bedeutung/Wortart/Wortformen/Quellenangabe)
🔍 Rückverfolgbar: Jeder Wissenspunkt trägt
Vorlesung · Abschnittspfad · Seitenzahl, kann zum Originaltext zurückverfolgt werden🗄️ Keine Abschneidung: Inhalt wird in SQLite
TEXTgespeichert (keine Längenbegrenzung), FTS dient nur der Trefferermittlung🌐 HTTP-API: Integrierter REST-Dienst (FastAPI, mit integrierter
/docs-Interaktionsdokumentation)🔌 MCP-bereit: Integrierter MCP-Dienst, direkt abfragbar von Clients wie Claude
Related MCP server: PDF RAG MCP Server
Schnellstart
uv sync # 安装依赖(含开发依赖)
uv run grammar-kb ingest ./pdfs # 导入一个 PDF 目录(全量重建,id 可复现)
uv run grammar-kb stats # 查看统计uv nicht installiert?
curl -LsSf https://astral.sh/uv/install.sh | sh
Häufige Befehle
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)Standarddatenbank ist data/grammar.db im aktuellen Verzeichnis; überschreibbar mit --db oder der Umgebungsvariable GRAMMAR_KB_DB.
Vorgefertigten Datensatz direkt verwenden (optional)
Wer nicht selbst ingestieren möchte, kann die passende grammar.db von GitHub Releases herunterladen, unter data/grammar.db ablegen (oder Pfad mit GRAMMAR_KB_DB angeben) und direkt abfragen. Die Datensatzversion steht im Release-Tag (z. B. data-v1); die meta-Tabelle in der Datenbank protokolliert ebenfalls Version und Erstellungszeit.
Architektur
PDF ──► pdf_parser 去水印(字体+方向过滤)+ 重排行 + 还原表格
└─► structure 文本 → 大纲树 → 知识点切分(分类 + 关键词 + 关系)
└─► db SQLite(lecture / knowledge_point / marker / relation / block + FTS5)
└─► query 查询 API(CLI 与 MCP 共用)Modul | Zuständigkeit |
| fitz extrahiert Spans (Schriftart/Position/Richtung) → filtert Wasserzeichen → sortiert Zeilen neu; pdfplumber rekonstruiert Tabellen auf den gefilterten Zeichen |
| Zeilenklassifikation (Abschnitt/Unterabschnitt/Unterpunkt/Beispielsatz/Übung) → Wissenspunkt-Segmentierung |
| Klassifikationsregeln, Schlüsselwort-Wörterbuch, Beziehungserkennung, Prüfungssignale (pure Funktionen) |
| Korpusbasierte Vokabelliste (Bedeutung/Wortart/Wortformen) |
| Tabelle → GFM, Rendering von Wissenspunkten und ganzen Vorlesungen |
| Schema + CRUD + FTS5(trigram, external-content), keine Abschneidung |
| Aufruforientierte Abfrage-API |
| PDF → Datenbank (Verzeichnisimport = vollständiger Neuaufbau, id reproduzierbar) |
| Separate SQLite-Datenbank für Hausaufgabennoten (CRUD; standardmäßig in iCloud Drive) |
| Kommandozeile |
| HTTP-Dienst (optionales Extra) |
| MCP-Dienst (optionales Extra) |
| Lern-Frontend (Vite, Details siehe unten „Web-Lern-Frontend" und |
Datenbank-Schema (Zusammenfassung)
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');Eigenen Datensatz anpassen
Die Werkzeuge sind standardmäßig auf „einheitlich formatierte Lehrskripte" abgestimmt. Beim Wechsel des Datensatzes sind meist nur drei Stellen anzupassen (alle in grammar_kb/):
Wasserzeichenschrift –
WATERMARK_FONTSinpdf_parser.py: Neue Kopfzeilen-/Wasserzeichenschriftnamen ergänzen. Schnellskript zur Diagnose von Schriftarten neuer PDFs: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)"Klassifikationsregeln –
_TITLE_RULESinclassify.py: Titel-Schlüsselwörter auf Themenklassifikation mappen.Schlüsselwort-Wörterbuch –
TENSE_MARKERSinclassify.py(oder ein eigenes gleichartiges Wörterbuch).Layout-Regex –
structure.py: Falls Ihre Überschriftenebenen andere Markierungen verwenden (z. B.一、/(一)), passen Sie die entsprechenden Regexe an.
Als HTTP-Dienst
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 8000Nach dem Start http://127.0.0.1:8000/docs aufrufen, um die interaktive API-Dokumentation zu sehen. Endpunkte:
Methode | Pfad | Beschreibung |
GET |
| Statistiken und Datensatz-Metainformationen |
GET |
| Vorlesungsliste |
GET |
| Inhalt einer Vorlesung (Tabellenrekonstruktion) |
GET |
| Ein Wissenspunkt |
GET |
| Volltextsuche |
GET |
| Signalmarker |
GET |
| Nach Beziehung suchen |
GET |
| Alle Prüfungssignal-Dimensionen |
GET |
| Wissenspunkte anhand von Prüfungssignalen rückwärts suchen |
GET |
| Vokabelliste (Bedeutung/Wortart/Wortformen) |
GET |
| Themen-Systembaum der Wissenspunkte (Oberkategorie→Thema) |
GET |
| Beliebiges Wort nachschlagen (ECDICT-Vollwörterbuch) |
GET/POST |
| Hausaufgabennoten: Liste / neu anlegen |
PUT/DELETE |
| Hausaufgabennoten: ändern / löschen |
Wo die Hausaufgabennoten gespeichert werden
Die Noten liegen in einer separaten SQLite-Datenbank (getrennt von der Skript-Datenbank data/grammar.db), Pfadauflösung in dieser Reihenfolge:
Umgebungsvariable
GRAMMAR_KB_EXAM_DBiCloud Drive:
~/Library/Mobile Documents/com~apple~CloudDocs/grammar-kb/exam.db(macOS und iCloud verfügbar) – kleine Datenmenge, in der Cloud, von iCloud über mehrere Geräte synchronisiertFallback
data/exam.db
Die Datenbank verwendet bewusst kein WAL-Modus (einzelne selbstenthaltende Datei, zuverlässigere iCloud-Ganzdatei-Synchronisation); auf anderen Geräten das Repo installieren, mit demselben iCloud-Konto anmelden und den Dienst starten – gelesen wird dieselbe Notensammlung.
Beispiel:
curl "http://127.0.0.1:8000/search?q=现在完成时&limit=3"
curl "http://127.0.0.1:8000/lectures/25?format=html"Einheitliches Antwortformat: Alle Endpunkte geben {code, message, data} zurück.
// 成功(HTTP 200)
{ "code": 0, "message": "ok", "data": { "knowledge_points": 359, ... } }
// 错误(HTTP 与 code 一致)
{ "code": 404, "message": "第 99 讲不存在", "data": null }CORS: Standardmäßig sind alle Ursprünge erlaubt (Access-Control-Allow-Origin: *), das Frontend kann direkt domänenübergreifend aufrufen.
Whitelist einschränken: GRAMMAR_KB_CORS_ORIGINS=https://a.com,https://b.com grammar-kb-server.
Als MCP-Dienst
uv sync --extra mcp
uv run grammar-kb-mcpBereitgestellte Tools: search_knowledge_points, get_knowledge_point, get_lecture_markdown,
list_lectures, list_markers, find_by_relation, stats. Jedes Tool ist ein dünner Wrapper um Query.
Claude-Desktop-Konfigurationsbeispiel:
{
"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-Lern-Frontend (web/)
Lernoberfläche für Studierende, abhängig vom lokal laufenden Backend-Dienst (Standard http://127.0.0.1:8000``, in der Entwicklung von Vite über /api/*` weitergeleitet).
# 终端 1:先起后端
uv sync --extra server && uv run grammar-kb-server
# 终端 2:再起前端
cd web && npm install && npm run dev # http://localhost:5180Funktionen:
Nach Kurs durchsuchen: 48 Vorlesungen gruppiert nach Grammatiksystem (Wortarten/Tempus/Diathese/Nicht-finite Verbformen/Syntax/Umfassende Wiederholung), Klick öffnet die ganze Vorlesung
Vokabelliste: 600+ häufige Wörter (Bedeutung/Wortart/Wortformen/Skript-Quelle), nach Wortart filtern, suchen, sortieren
Wissenssystem: 359 verstreute Wissenspunkte aggregiert zu zweistufigem Baum „Grammatik-Oberkategorie → Thema", inkl. Schnellnachschlagetabelle für feste Wendungen
🎯 Prüfungssignale (bidirektional): Wissenspunkt ↔ Signalmarker/Tempus bidirektional springen – „Wenn ich dieses Wort sehe, welche Wissenspunkte werden geprüft"
📝 Hausaufgabennoten: Pro Vorlesung ein Aufgabenblatt (35 Aufgaben, 100 Punkte). Auf Aufgabennummer klicken für richtig/falsch, Punktzahl wird automatisch berechnet; mehrere Versuche bleiben alle erhalten, änderbar und löschbar; Fehlerheft fasst Fehlerhäufigkeit nach „Vorlesung+Aufgabennummer" zusammen; Daten werden über das Backend
/examsin iCloud gespeichert (siehe oben), gehen über Browser/Geräte nicht verloren, alte localStorage-Einträge werden beim ersten Öffnen automatisch migriert
Technologie-Stack: Vite + native ES-Module · marked (Markdown-Rendering), ohne Framework-Abhängigkeit. Weitere Details in web/README.md.
Tests
uv run pytest # 全部(含真实 PDF 集成)
uv run pytest -m "not integration" # 仅纯单测(无需 PDF,秒级)Abgedeckt: Wasserzeichenfilterung / Zeilen-Neusortierung / Tabellenrekonstruktion / Wissenspunkt-Segmentierung / Klassifikation / Schlüsselwort-Extraktion / DB-Roundtrip ohne Abschneidung / FTS chinesisch-englische Suche / kaskadierende Bereinigung / reproduzierbarer id-Neuaufbau / Abfragen / End-to-End-Integration.
Integrationstests benötigen ein PDF-Verzeichnis, angegeben über die Umgebungsvariable GRAMMAR_TEST_PDF_DIR; nicht angegeben oder nicht vorhanden → automatisch übersprungen.
Design-Entscheidungen und bekannte Grenzen
Tabellen ohne Rahmenlinien: Es werden nur ruled tables rekonstruiert, die pdfplumber anhand von Rahmenlinien erkennen kann; wenige rahmenlose Mehrspalten-Vergleiche bleiben als Fließtextabsätze erhalten (Informationen gehen nicht verloren). Später kann eine Fallback-Erkennung „Ausrichtung nach Spalten-Leerzeichen" ergänzt werden.
Wissenspunkt-Segmentierung: Heuristik basierend auf einheitlichem Layout; bei speziellen Layouts können Zusammenführungen/Aufteilungen leicht abweichen – mit
search+kpüberprüfbar.Verzeichnisimport = Neuaufbau:
ingest <Verzeichnis>leert und baut die Datenbank neu auf (id beginnt bei 1, reproduzierbar); Import eines einzelnen PDFs aktualisiert nur diese Vorlesung.
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-