Skip to main content
Glama
grammar-kb-mcp

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 TEXT gespeichert (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

pdf_parser.py

fitz extrahiert Spans (Schriftart/Position/Richtung) → filtert Wasserzeichen → sortiert Zeilen neu; pdfplumber rekonstruiert Tabellen auf den gefilterten Zeichen

structure.py

Zeilenklassifikation (Abschnitt/Unterabschnitt/Unterpunkt/Beispielsatz/Übung) → Wissenspunkt-Segmentierung

classify.py

Klassifikationsregeln, Schlüsselwort-Wörterbuch, Beziehungserkennung, Prüfungssignale (pure Funktionen)

vocabulary.py

Korpusbasierte Vokabelliste (Bedeutung/Wortart/Wortformen)

markdown.py

Tabelle → GFM, Rendering von Wissenspunkten und ganzen Vorlesungen

db.py

Schema + CRUD + FTS5(trigram, external-content), keine Abschneidung

query.py

Aufruforientierte Abfrage-API

ingest.py

PDF → Datenbank (Verzeichnisimport = vollständiger Neuaufbau, id reproduzierbar)

exam_store.py

Separate SQLite-Datenbank für Hausaufgabennoten (CRUD; standardmäßig in iCloud Drive)

cli.py

Kommandozeile

server.py

HTTP-Dienst (optionales Extra)

mcp_server.py

MCP-Dienst (optionales Extra)

web/

Lern-Frontend (Vite, Details siehe unten „Web-Lern-Frontend" und web/README.md)


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_FONTS in pdf_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_RULES in classify.py: Titel-Schlüsselwörter auf Themenklassifikation mappen.

  • Schlüsselwort-Wörterbuch – TENSE_MARKERS in classify.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 8000

Nach dem Start http://127.0.0.1:8000/docs aufrufen, um die interaktive API-Dokumentation zu sehen. Endpunkte:

Methode

Pfad

Beschreibung

GET

/stats

Statistiken und Datensatz-Metainformationen

GET

/lectures

Vorlesungsliste

GET

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

Inhalt einer Vorlesung (Tabellenrekonstruktion)

GET

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

Ein Wissenspunkt

GET

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

Volltextsuche

GET

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

Signalmarker

GET

/relation?type=主将从现

Nach Beziehung suchen

GET

/exam-signals

Alle Prüfungssignal-Dimensionen

GET

/exam-signal?signal=时态

Wissenspunkte anhand von Prüfungssignalen rückwärts suchen

GET

/vocabulary?limit=300&min_freq=2

Vokabelliste (Bedeutung/Wortart/Wortformen)

GET

/taxonomy

Themen-Systembaum der Wissenspunkte (Oberkategorie→Thema)

GET

/dict/{word}

Beliebiges Wort nachschlagen (ECDICT-Vollwörterbuch)

GET/POST

/exams

Hausaufgabennoten: Liste / neu anlegen

PUT/DELETE

/exams/{id}

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:

  1. Umgebungsvariable GRAMMAR_KB_EXAM_DB

  2. iCloud 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 synchronisiert

  3. Fallback 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-mcp

Bereitgestellte 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:5180

Funktionen:

  • 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 /exams in 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 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
      -