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 共用)Модуль | Назначение |
| fitz извлекает span (шрифт/позиция/направление) → фильтрация водяных знаков → перестройка строк; pdfplumber восстанавливает таблицы по отфильтрованным символам |
| Классификация строк (раздел/подраздел/пункт/пример/упражнение) → разбиение на фрагменты знаний |
| Правила классификации, словарь ключевых слов, обнаружение связей, экзаменационные сигналы (чистые функции) |
| Словарь на основе корпуса (значение / часть речи / словоформы) |
| Таблицы → GFM, рендеринг фрагментов знаний и лекций |
| schema + CRUD + FTS5(trigram, external-content), без обрезки |
| API запросов для вызова |
| PDF → запись в БД (импорт каталога = полное пересоздание, id воспроизводимы) |
| Отдельная SQLite-база оценок за работы (CRUD; по умолчанию в iCloud Drive) |
| Командная строка |
| HTTP-сервис (опциональный extra) |
| MCP-сервис (опциональный extra) |
| Учебный фронтенд (Vite, подробнее см. ниже «Web-фронтенд» и |
Схема базы данных (кратко)
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 |
| Статистика и метаинформация набора данных |
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: *), фронтенд может вызывать 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 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-