grammar-kb-mcp
grammar-kb
Repositorio monorepo de base de conocimiento + frontend de aprendizaje para apuntes de enseñanza de gramática inglesa, organizado en dos capas:
grammar_kb/(backend en Python): limpia y estructura los PDF de materiales/apuntes en una base de datos de puntos de conocimiento consultable y trazable: elimina automáticamente marcas de agua, restaura tablas, segmenta puntos de conocimiento, extrae palabras clave y relaciones, y lo almacena en SQLite local (búsqueda de texto completo FTS5), con CLI, API HTTP y servicio MCP.web/(frontend en Vite): interfaz de aprendizaje para estudiantes — permite explorar los apuntes de tres formas: por curso / glosario / sistema de conocimiento, además de un registro de calificaciones de tareas (CRUD, persistido en iCloud Drive, sincronizado entre dispositivos).
Apto para cualquier PDF de enseñanza/técnica con "maquetación relativamente uniforme, encabezados/pies de página con marcas de agua y tablas".
Características
🧹 Eliminación de marcas de agua: filtra encabezados/pies de página y marcas de agua diagonales de fondo según fuente + orientación del texto (incluidos prefijos de fuentes subconjunto de PDF)
📊 Restauración de tablas: detecta automáticamente tablas con bordes y las restaura como tablas GFM Markdown
🧩 Segmentación de puntos de conocimiento: divide por niveles de título (capítulo/sección/subsección/subítem/ejemplo/ejercicio) en unidades consultables de forma independiente
🏷️ Clasificación y relaciones: clasifica por tema, extrae palabras clave/marcadores y relaciones entre puntos de conocimiento (como "principal en futuro, subordinada en presente" o "concordancia de tiempos")
🎯 Señales de examen: cada punto de conocimiento se etiqueta con su dimensión de examen (tiempo verbal/voz/ortografía/subordinadas…), con soporte para "buscar puntos de conocimiento por señal de examen"
📖 Lista de vocabulario: genera listas de vocabulario a partir del corpus de los apuntes (definición/categoría gramatical/forma flexiva/trazabilidad de origen)
🔍 Trazable: cada punto de conocimiento incluye
sesión · ruta de sección · número de página, localizable en el texto original🗄️ Sin truncamiento: el cuerpo del texto se almacena en SQLite
TEXT(sin límite de longitud); FTS se usa solo para coincidencias🌐 API HTTP: servicio REST integrado (FastAPI, con documentación interactiva
/docs)🔌 Listo para MCP: servicio MCP integrado; clientes como Claude pueden consultarlo directamente
Related MCP server: PDF RAG MCP Server
Inicio rápido
uv sync # 安装依赖(含开发依赖)
uv run grammar-kb ingest ./pdfs # 导入一个 PDF 目录(全量重建,id 可复现)
uv run grammar-kb stats # 查看统计¿No tienes uv instalado?
curl -LsSf https://astral.sh/uv/install.sh | sh
Comandos habituales
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)La base de datos predeterminada es data/grammar.db en el directorio de ejecución; se puede sobrescribir con --db o con la variable de entorno GRAMMAR_KB_DB.
Usar un conjunto de datos precompilado (opcional)
Si no quieres hacer el ingest tú mismo, puedes descargar el grammar.db de la versión correspondiente desde GitHub Releases, colocarlo en data/grammar.db (o especificar la ruta con GRAMMAR_KB_DB) y consultarlo directamente. El número de versión del conjunto de datos aparece en la etiqueta del release (p. ej. data-v1); la tabla meta de la base de datos también registra la versión y la hora de generación.
Arquitectura
PDF ──► pdf_parser 去水印(字体+方向过滤)+ 重排行 + 还原表格
└─► structure 文本 → 大纲树 → 知识点切分(分类 + 关键词 + 关系)
└─► db SQLite(lecture / knowledge_point / marker / relation / block + FTS5)
└─► query 查询 API(CLI 与 MCP 共用)Módulo | Responsabilidad |
| fitz extrae spans (fuente/posición/orientación) → filtra marcas de agua → reordena líneas; pdfplumber restaura tablas sobre los caracteres ya filtrados |
| Clasificación de líneas (sección/subsección/subítem/ejemplo/ejercicio) → segmentación de puntos de conocimiento |
| Reglas de clasificación, diccionario de palabras clave, detección de relaciones, señales de examen (funciones puras) |
| Lista de vocabulario basada en el corpus (definición/categoría gramatical/forma flexiva) |
| Tablas → GFM, renderizado de puntos de conocimiento y sesiones completas |
| schema + CRUD + FTS5(trigram, external-content), sin truncamiento |
| API de consulta orientada a llamadas |
| PDF → persistencia en base de datos (importación de directorio = reconstrucción completa, id reproducible) |
| Base de datos SQLite independiente para calificaciones de tareas (CRUD; por defecto en iCloud Drive) |
| Línea de comandos |
| Servicio HTTP (extra opcional) |
| Servicio MCP (extra opcional) |
| Frontend de aprendizaje (Vite; ver más abajo «Frontend web de aprendizaje» y |
Esquema de la base de datos (resumen)
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');Personalizar tu conjunto de datos
La herramienta está ajustada por defecto para "apuntes de enseñanza con maquetación uniforme". Al cambiar de conjunto de datos normalmente solo hay que tocar tres sitios (todos en grammar_kb/):
Fuentes de marca de agua —
WATERMARK_FONTSenpdf_parser.py: añade los nombres de fuente de tus encabezados/marcas de agua. Script rápido para diagnosticar las fuentes de un PDF nuevo: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)"Reglas de clasificación —
_TITLE_RULESenclassify.py: asigna la clasificación temática según palabras clave del título.Diccionario de palabras clave —
TENSE_MARKERSenclassify.py(o diccionarios personalizados similares).Expresiones regulares de maquetación —
structure.py: si tus niveles de título usan marcadores distintos (como一、/(一)), ajusta las expresiones regulares correspondientes.
Como servicio 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 8000Tras iniciarlo, visita http://127.0.0.1:8000/docs para ver la documentación interactiva de la API. Endpoints:
Método | Ruta | Descripción |
GET |
| Estadísticas e información de metadatos del conjunto de datos |
GET |
| Lista de sesiones |
GET |
| Contenido de una sesión (con tablas restauradas) |
GET |
| Un punto de conocimiento |
GET |
| Búsqueda de texto completo |
GET |
| Palabras marcadoras |
GET |
| Consulta por relación |
GET |
| Todas las dimensiones de señales de examen |
GET |
| Búsqueda de puntos de conocimiento por señal de examen |
GET |
| Lista de vocabulario (definición/categoría gramatical/forma flexiva) |
GET |
| Árbol del sistema temático de puntos de conocimiento (categoría general → tema) |
GET |
| Consulta de cualquier palabra (diccionario completo ECDICT) |
GET/POST |
| Calificaciones de tareas: listar / añadir |
PUT/DELETE |
| Calificaciones de tareas: modificar / eliminar |
Dónde se guardan los datos de calificaciones
Las calificaciones se guardan en una base de datos SQLite independiente (separada de la base de apuntes data/grammar.db). La ruta se resuelve en este orden:
Variable de entorno
GRAMMAR_KB_EXAM_DBiCloud Drive:
~/Library/Mobile Documents/com~apple~CloudDocs/grammar-kb/exam.db(en macOS cuando iCloud está disponible) — el volumen de datos es pequeño; al estar en la nube, iCloud lo sincroniza entre varios dispositivosRespaldo:
data/exam.db
La base de datos usa deliberadamente el modo sin WAL (archivo único autocontenido; la sincronización de archivos completos de iCloud es más fiable); en otro dispositivo, tras instalar este repositorio e iniciar sesión con la misma cuenta de iCloud e iniciar el servicio, se leen las mismas calificaciones.
Ejemplo:
curl "http://127.0.0.1:8000/search?q=现在完成时&limit=3"
curl "http://127.0.0.1:8000/lectures/25?format=html"Formato de respuesta unificado: todos los endpoints devuelven {code, message, data}.
// 成功(HTTP 200)
{ "code": 0, "message": "ok", "data": { "knowledge_points": 359, ... } }
// 错误(HTTP 与 code 一致)
{ "code": 404, "message": "第 99 讲不存在", "data": null }CORS: por defecto se permiten todos los orígenes (Access-Control-Allow-Origin: *); el frontend puede hacer llamadas entre dominios directamente.
Para restringir la lista blanca: GRAMMAR_KB_CORS_ORIGINS=https://a.com,https://b.com grammar-kb-server.
Como servicio MCP
uv sync --extra mcp
uv run grammar-kb-mcpHerramientas expuestas: search_knowledge_points, get_knowledge_point, get_lecture_markdown,
list_lectures, list_markers, find_by_relation, stats. Cada herramienta es un envoltorio ligero sobre Query.
Ejemplo de configuración de 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" }
}
}
}Frontend web de aprendizaje (web/)
Interfaz de aprendizaje para estudiantes; depende del servicio backend en ejecución local (por defecto http://127.0.0.1:8000; en desarrollo, Vite redirige /api/\*\ hacia él).
# 终端 1:先起后端
uv sync --extra server && uv run grammar-kb-server
# 终端 2:再起前端
cd web && npm install && npm run dev # http://localhost:5180Funciones:
Explorar por curso: 48 sesiones agrupadas por sistema gramatical (morfología/tiempos verbales/voz/formas no personales/sintaxis/revisión integral); al hacer clic se ve el contenido completo de la sesión
Glosario: más de 600 palabras de alta frecuencia (definición/categoría gramatical/forma flexiva/origen en los apuntes), con filtro por categoría gramatical, búsqueda y ordenación
Sistema de conocimiento: 359 puntos de conocimiento dispersos agregados en un árbol de dos niveles «categoría gramatical general → tema», con tabla de consulta rápida de colocaciones fijas
🎯 Señales de examen (bidireccional): salto bidireccional entre puntos de conocimiento ↔ palabras marcadoras/tiempos verbales — «al ver esta palabra, ¿qué puntos de conocimiento se están evaluando?»
📝 Calificaciones de tareas: una hoja de ejercicios por sesión (35 preguntas, 100 puntos). Haz clic en el número de pregunta para marcar correcto/incorrecto; la puntuación se calcula automáticamente; se conservan todos los intentos múltiples, se pueden modificar y eliminar; el cuaderno de errores resume el número de errores por «sesión + número de pregunta»; los datos se guardan en iCloud a través del endpoint
/examsdel backend (ver arriba), sin pérdidas entre navegadores/dispositivos; los registros antiguos de localStorage se migran automáticamente en la primera apertura
Pila técnica: Vite + ES Modules nativos · marked (renderizado Markdown), sin dependencias de frameworks. Más detalles en web/README.md.
Pruebas
uv run pytest # 全部(含真实 PDF 集成)
uv run pytest -m "not integration" # 仅纯单测(无需 PDF,秒级)Cobertura: filtrado de marcas de agua / reordenación de líneas / restauración de tablas / segmentación de puntos de conocimiento / clasificación / extracción de palabras clave / ida y vuelta sin truncamiento en DB / búsqueda FTS en chino e inglés / limpieza en cascada / reconstrucción reproducible de id / consultas / integración de extremo a extremo.
Las pruebas de integración necesitan un directorio de PDF, especificado con la variable de entorno GRAMMAR_TEST_PDF_DIR; si no se especifica o no existe, se omiten automáticamente.
Compromisos de diseño y límites conocidos
Tablas sin bordes: solo se restauran las tablas con reglas que pdfplumber pueda detectar por sus líneas; las pocas comparaciones multicolumna sin bordes se conservan como párrafos del cuerpo (la información no se pierde). En el futuro se puede añadir una detección de respaldo por "alineación de columnas por espacios".
Segmentación de puntos de conocimiento: heurística basada en maquetación uniforme; con maquetaciones especiales puede haber ligeras diferencias de fusión/división; se puede verificar con
search+kp.Importación de directorio = reconstrucción:
ingest <directorio>vacía y reconstruye la base de datos (id desde 1, reproducible); importar un único PDF solo actualiza esa sesión.
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-