grammar-kb-mcp
grammar-kb
英語文法教材のナレッジベース + 学習フロントエンドのモノレポプロジェクト。2層構成です:
grammar_kb/(Python バックエンド):PDF教材/講義をクリーニング・構造化し、検索可能・出典追跡可能な知識ポイントデータベースに変換します—— 自動で透かし除去、テーブル復元、知識ポイント分割、キーワードと関係の抽出を行い、ローカル SQLite(FTS5 全文検索)に格納します。 CLI、HTTP API、MCP サービスを提供します。web/(Vite フロントエンド):学生向けの学習インターフェース——コース / 語彙表 / 知識体系の3つの方法で講義を閲覧でき、 さらに課題成績の記録(CRUD、iCloud Drive に永続化、デバイス間で同期)も可能です。
「レイアウトが比較的統一され、ヘッダー/フッターの透かしがあり、テーブルを含む」教育用・技術用 PDF に適用できます。
特徴
🧹 透かし除去:フォント + 文字方向でヘッダー/フッター/斜め背景の透かしを除去(PDF サブセットフォントプレフィックス対応)
📊 テーブル復元:枠線のあるテーブルを自動検出し、GFM Markdown テーブルに復元
🧩 知識ポイント分割:見出し階層(章/節/小節/子項目/例文/練習)に従って独立して検索可能なユニットに分割
🏷️ 分類と関係:テーマ別に分類し、キーワード/シグナルワードと知識ポイント間の関係(「主節は未来形・従属節は現在形」「時制の呼応」など)を抽出
🎯 試験シグナル:各知識ポイントに試験の観点(時制/態/スペル/節…)を付与し、「試験観点から知識ポイントを逆引き」をサポート
📖 単語表:講義コーパスに基づいて単語表を生成(意味/品詞/語形変化/出典の追跡)
🔍 出典追跡可能:各知識ポイントに「講次 · 節パス · ページ番号」が付き、原文に戻れます
🗄️ 切り詰めなし:本文は SQLite
TEXTに保存(長さ上限なし)、FTS はヒット判定のみに使用🌐 HTTP API:REST サービス内蔵(FastAPI、
/docs対話ドキュメント付き)🔌 MCP 対応:MCP サービス内蔵、Claude などのクライアントから直接クエリ可能
Related MCP server: PDF RAG MCP Server
クイックスタート
uv sync # 安装依赖(含开发依赖)
uv run grammar-kb ingest ./pdfs # 导入一个 PDF 目录(全量重建,id 可复现)
uv run grammar-kb stats # 查看统计uv をインストールしていない場合:
curl -LsSf https://astral.sh/uv/install.sh | sh
よく使うコマンド
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)デフォルトのデータベースは実行ディレクトリの data/grammar.db です。--db または環境変数 GRAMMAR_KB_DB で上書きできます。
ビルド済みデータセットを直接使う(任意)
自分で ingest したくない場合は、GitHub Releases から対応バージョンの grammar.db をダウンロードし、data/grammar.db に置く(または GRAMMAR_KB_DB でパスを指定する)だけで直接クエリできます。データセットのバージョン番号は release tag(例:data-v1)に記載されており、ライブラリ内の meta テーブルにもバージョンと生成時刻が記録されています。
アーキテクチャ
PDF ──► pdf_parser 去水印(字体+方向过滤)+ 重排行 + 还原表格
└─► structure 文本 → 大纲树 → 知识点切分(分类 + 关键词 + 关系)
└─► db SQLite(lecture / knowledge_point / marker / relation / block + FTS5)
└─► query 查询 API(CLI 与 MCP 共用)モジュール | 役割 |
| fitz で span(フォント/位置/方向)を抽出 → 透かしをフィルタリング → 行を再構成;pdfplumber でフィルタリング後の文字上でテーブルを復元 |
| 行の分類(節/小節/子項目/例文/練習)→ 知識ポイント分割 |
| 分類ルール、キーワード辞書、関係検出、試験シグナル(純関数) |
| コーパスに基づく単語表(意味/品詞/語形変化) |
| テーブル → GFM、知識ポイントと講義全体のレンダリング |
| schema + CRUD + FTS5(trigram, external-content)、切り詰めなし |
| 呼び出し向けのクエリ API |
| PDF → データベース格納(ディレクトリ取り込み = 全量再構築、id は再現可能) |
| 課題成績の独立 SQLite ライブラリ(CRUD;デフォルトは iCloud Drive) |
| コマンドライン |
| HTTP サービス(オプションの extra) |
| MCP サービス(オプションの extra) |
| 学習フロントエンド(Vite、詳細は下記「Web 学習フロントエンド」と |
データベース Schema(概要)
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');データセットのカスタマイズ
このツールはデフォルトで「レイアウトが統一された教育用講義」向けに調整されています。データセットを変更する場合、通常は3箇所(すべて grammar_kb/ 内)を変更するだけです:
透かしフォント ——
pdf_parser.pyのWATERMARK_FONTS:新しいヘッダー/透かしフォント名を追加します。 新しい 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)"分類ルール ——
classify.pyの_TITLE_RULES:見出しキーワードでテーマ分類をマッピングします。キーワード辞書 ——
classify.pyのTENSE_MARKERS(またはカスタムの同種辞書)。レイアウト正規表現 ——
structure.py:見出し階層で異なる記号(例:一、/(一))を使う場合は、対応する正規表現を調整します。
HTTP サービスとして
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起動後、http://127.0.0.1:8000/docs にアクセスして対話型 API ドキュメントを確認できます。エンドポイント:
メソッド | パス | 説明 |
GET |
| 統計とデータセットのメタ情報 |
GET |
| 講次一覧 |
GET |
| 特定の講義内容(テーブル復元) |
GET |
| 特定の知識ポイント |
GET |
| 全文検索 |
GET |
| シグナルワード |
GET |
| 関係で検索 |
GET |
| すべての試験シグナル次元 |
GET |
| 試験観点から知識ポイントを逆引き |
GET |
| 単語表(意味/品詞/語形変化) |
GET |
| 知識ポイントのテーマ体系ツリー(大分類→テーマ) |
GET |
| 任意の単語を検索(ECDICT 全量辞書) |
GET/POST |
| 課題成績:一覧 / 追加 |
PUT/DELETE |
| 課題成績:変更 / 削除 |
課題成績データの保存場所
成績は独立した SQLite ライブラリ(講義ライブラリ data/grammar.db とは別)に保存され、パスは次の順序で解決されます:
環境変数
GRAMMAR_KB_EXAM_DBiCloud Drive:
~/Library/Mobile Documents/com~apple~CloudDocs/grammar-kb/exam.db(macOS かつ iCloud が利用可能な場合)——データ量が少ないため、クラウドに置いて iCloud で複数デバイス間で同期しますフォールバック
data/exam.db
ライブラリは意図的に WAL モードを使用していません(単一ファイルで自己完結し、iCloud のファイル全体同期の方が信頼性が高いため)。他のデバイスでこのリポジトリをセットアップし、同じ iCloud アカウントにログインしてサービスを起動すると、同じ成績が読み込まれます。
例:
curl "http://127.0.0.1:8000/search?q=现在完成时&limit=3"
curl "http://127.0.0.1:8000/lectures/25?format=html"統一レスポンス形式:すべてのエンドポイントは {code, message, data} を返します。
// 成功(HTTP 200)
{ "code": 0, "message": "ok", "data": { "knowledge_points": 359, ... } }
// 错误(HTTP 与 code 一致)
{ "code": 404, "message": "第 99 讲不存在", "data": null }CORS:デフォルトですべてのオリジンを許可(Access-Control-Allow-Origin: *)、フロントエンドから直接クロスオリジン呼び出しが可能です。ホワイトリストを絞り込む場合:GRAMMAR_KB_CORS_ORIGINS=https://a.com,https://b.com grammar-kb-server。
MCP サービスとして
uv sync --extra mcp
uv run grammar-kb-mcp公開される tools:search_knowledge_points、get_knowledge_point、get_lecture_markdown、
list_lectures、list_markers、find_by_relation、stats。各 tool は Query の薄いラッパーです。
Claude Desktop の設定例:
{
"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 学習フロントエンド(web/)
学生向けの学習インターフェースで、ローカルで実行中のバックエンドサービス(デフォルト http://127.0.0.1:8000``、開発中は Vite が /api/*` をプロキシ)に依存します。
# 终端 1:先起后端
uv sync --extra server && uv run grammar-kb-server
# 终端 2:再起前端
cd web && npm install && npm run dev # http://localhost:5180機能:
コース別ブラウズ:48講を文法体系(語法/時制/態/非述語/構文/総合復習)でグループ化し、クリックで講義全体を表示
語彙表:600+ の高頻度語(意味/品詞/語形変化/講義の出典)、品詞でフィルタリング、検索、並べ替え
知識体系:359 の散在する知識ポイントを「文法大分類 → テーマ」の2階層ツリーに集約、定型表現の早見表付き
🎯 試験シグナル(双方向):知識ポイント ↔ シグナルワード/時制の双方向ジャンプ——「この単語を見たら、どの知識ポイントが問われているか」
📝 課題成績:各講義に1枚の課題(35問、満点100)。問題番号をクリックして正誤を記録、スコアは自動計算; 複数回の回答はすべて保持され、修正・削除も可能;間違いノートは「講次+問題番号」で誤り回数を集計; データはバックエンドの
/exams経由で iCloud に保存(上記参照)、ブラウザ/デバイスをまたいでも失われず、旧 localStorage の記録は初回起動時に自動移行
技術スタック:Vite + ネイティブ ES Modules · marked(Markdown レンダリング)、フレームワーク依存なし。詳細は web/README.md を参照。
テスト
uv run pytest # 全部(含真实 PDF 集成)
uv run pytest -m "not integration" # 仅纯单测(无需 PDF,秒级)カバレッジ:透かしフィルタリング / 行の再構成 / テーブル復元 / 知識ポイント分割 / 分類 / キーワード抽出 / DB の切り詰めなし往復 / FTS の中国語・英語検索 / カスケード削除 / id 再構築の再現性 / クエリ / エンドツーエンド統合。
統合テストには PDF ディレクトリが必要で、環境変数 GRAMMAR_TEST_PDF_DIR で指定します。未指定または存在しない場合は自動的にスキップされます。
設計上のトレードオフと既知の制限
枠線のないテーブル:pdfplumber が枠線で検出できる ruled table のみ復元します。少数の枠線なしの多段対照は本文段落として保持されます(情報は失われません)。今後「列の空白揃え」によるフォールバック検出を追加予定です。
知識ポイント分割:統一レイアウトに基づくヒューリスティックです。特殊なレイアウトでは結合/分割が多少ずれる可能性があるため、
search+kpで確認できます。ディレクトリ取り込みは再構築:
ingest <ディレクトリ>はライブラリをクリアして再構築します(id は1から始まり、再現可能)。単一 PDF の取り込みはその講のみ更新します。
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-