Skip to main content
Glama
grammar-kb-mcp

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 共用)

モジュール

役割

pdf_parser.py

fitz で span(フォント/位置/方向)を抽出 → 透かしをフィルタリング → 行を再構成;pdfplumber でフィルタリング後の文字上でテーブルを復元

structure.py

行の分類(節/小節/子項目/例文/練習)→ 知識ポイント分割

classify.py

分類ルール、キーワード辞書、関係検出、試験シグナル(純関数)

vocabulary.py

コーパスに基づく単語表(意味/品詞/語形変化)

markdown.py

テーブル → GFM、知識ポイントと講義全体のレンダリング

db.py

schema + CRUD + FTS5(trigram, external-content)、切り詰めなし

query.py

呼び出し向けのクエリ API

ingest.py

PDF → データベース格納(ディレクトリ取り込み = 全量再構築、id は再現可能)

exam_store.py

課題成績の独立 SQLite ライブラリ(CRUD;デフォルトは iCloud Drive)

cli.py

コマンドライン

server.py

HTTP サービス(オプションの extra)

mcp_server.py

MCP サービス(オプションの extra)

web/

学習フロントエンド(Vite、詳細は下記「Web 学習フロントエンド」と web/README.md)


データベース 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

/stats

統計とデータセットのメタ情報

GET

/lectures

講次一覧

GET

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

特定の講義内容(テーブル復元)

GET

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

特定の知識ポイント

GET

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

全文検索

GET

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

シグナルワード

GET

/relation?type=主将从现

関係で検索

GET

/exam-signals

すべての試験シグナル次元

GET

/exam-signal?signal=时态

試験観点から知識ポイントを逆引き

GET

/vocabulary?limit=300&min_freq=2

単語表(意味/品詞/語形変化)

GET

/taxonomy

知識ポイントのテーマ体系ツリー(大分類→テーマ)

GET

/dict/{word}

任意の単語を検索(ECDICT 全量辞書)

GET/POST

/exams

課題成績:一覧 / 追加

PUT/DELETE

/exams/{id}

課題成績:変更 / 削除

課題成績データの保存場所

成績は独立した SQLite ライブラリ(講義ライブラリ data/grammar.db とは別)に保存され、パスは次の順序で解決されます:

  1. 環境変数 GRAMMAR_KB_EXAM_DB

  2. iCloud Drive:~/Library/Mobile Documents/com~apple~CloudDocs/grammar-kb/exam.db(macOS かつ iCloud が利用可能な場合)——データ量が少ないため、クラウドに置いて iCloud で複数デバイス間で同期します

  3. フォールバック 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 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
      -