Skip to main content
Glama
grammar-kb-mcp

grammar-kb-mcp

grammar-kb

Монорепозиторий базы знаний + учебного фронтенда для конспектов по английской грамматике, состоящий из двух уровней:

  • grammar_kb/ (Python-бэкенд): очищает и структурирует PDF-учебники/конспекты в поисковую базу фрагментов знаний с прослеживаемостью источников — автоматически удаляет водяные знаки, восстанавливает таблицы, разбивает на фрагменты знаний, извлекает ключевые слова и связи, сохраняет в локальную SQLite (полнотекстовый поиск FTS5), предоставляет CLI, HTTP API и MCP-сервис.

  • web/ (фронтенд на Vite): учебный интерфейс для студентов — просмотр конспектов тремя способами: по курсам / глоссарию / системе знаний, плюс запись оценок за домашние задания (CRUD, сохраняется в iCloud Drive, синхронизация между устройствами).

Подходит для любых учебных/технических PDF с «относительно единообразной вёрсткой, водяными знаками в колонтитулах и таблицами».

Возможности

  • 🧹 Удаление водяных знаков: по шрифту + направлению текста отсекаются колонтитулы и наклонные фоновые водяные знаки (включая префиксы subset-шрифтов 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 самостоятельно, скачайте grammar.db нужной версии из GitHub Releases, поместите в data/grammar.db (или укажите путь через GRAMMAR_KB_DB) — и можно сразу выполнять запросы. Номер версии набора данных указан в теге релиза (например, 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)


Схема базы данных (кратко)

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');

Настройка вашего набора данных

Инструмент по умолчанию настроен на «учебные конспекты с единообразной вёрсткой»; при смене набора данных обычно нужно изменить только три места (все в grammar_kb/):

  • Шрифты водяных знаков — WATERMARK_FONTS в pdf_parser.py: добавьте имена шрифтов ваших колонтитулов/водяных знаков. Быстрый скрипт для диагностики шрифтов нового 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)"
  • Правила классификации — _TITLE_RULES в classify.py: сопоставление ключевых слов заголовков с тематическими категориями.

  • Словарь ключевых слов — TENSE_MARKERS в classify.py (или собственный аналогичный словарь).

  • Регулярные выражения вёрстки — 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: *), фронтенд может вызывать API напрямую с другого домена. Чтобы ужесточить белый список: GRAMMAR_KB_CORS_ORIGINS=https://a.com,https://b.com grammar-kb-server.

В качестве MCP-сервиса

uv sync --extra mcp
uv run grammar-kb-mcp

Предоставляемые инструменты: search_knowledge_points, get_knowledge_point, get_lecture_markdown, list_lectures, list_markers, find_by_relation, stats. Каждый инструмент — тонкая обёртка над 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 разрозненных фрагментов знаний объединены в двухуровневое дерево «грамматическая категория → тема», включая таблицу устойчивых сочетаний.

  • 🎯 Экзаменационные сигналы (двунаправленные): взаимные переходы между фрагментами знаний ↔ словами-маркерами/временами — «видишь это слово — значит, какие знания проверяются».

  • 📝 Оценки за работы: к каждой лекции — лист с заданиями (35 вопросов, максимум 100 баллов). Клик по номеру вопроса отмечает правильность, баллы считаются автоматически; все попытки сохраняются, их можно изменять и удалять; журнал ошибок сводит количество ошибок по «лекция + номер вопроса»; данные через бэкенд /exams сохраняются в iCloud (см. выше), не теряются между браузерами/устройствами, старые записи localStorage автоматически мигрируют при первом открытии.

Технологический стек: Vite + нативные ES-модули · marked (рендеринг Markdown), без зависимостей от фреймворков. Подробнее см. web/README.md.

Тестирование

uv run pytest                           # 全部(含真实 PDF 集成)
uv run pytest -m "not integration"      # 仅纯单测(无需 PDF,秒级)

Покрытие: фильтрация водяных знаков / перестройка строк / восстановление таблиц / разбиение на фрагменты знаний / классификация / извлечение ключевых слов / безобрезной цикл записи и чтения БД / полнотекстовый поиск FTS на китайском и английском / каскадная очистка / воспроизводимое пересоздание id / запросы / сквозная интеграция.

Для интеграционных тестов нужен каталог с PDF, задаваемый переменной окружения GRAMMAR_TEST_PDF_DIR; если он не задан или не существует, тесты автоматически пропускаются.

Компромиссы в дизайне и известные ограничения

  • Таблицы без рамок: восстанавливаются только ruled table, которые pdfplumber может обнаружить по линиям; небольшое количество безрамочных многоколоночных сопоставлений сохраняется как обычные абзацы (информация не теряется). Позже можно добавить запасное обнаружение по «выравниванию по пробелам в колонках».

  • Разбиение на фрагменты знаний: эвристика, основанная на единообразной вёрстке; при особой вёрстке возможны небольшие расхождения в объединении/разделении, можно перепроверить через 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
      -