Skip to main content
Glama
grammar-kb-mcp

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

pdf_parser.py

fitz extrae spans (fuente/posición/orientación) → filtra marcas de agua → reordena líneas; pdfplumber restaura tablas sobre los caracteres ya filtrados

structure.py

Clasificación de líneas (sección/subsección/subítem/ejemplo/ejercicio) → segmentación de puntos de conocimiento

classify.py

Reglas de clasificación, diccionario de palabras clave, detección de relaciones, señales de examen (funciones puras)

vocabulary.py

Lista de vocabulario basada en el corpus (definición/categoría gramatical/forma flexiva)

markdown.py

Tablas → GFM, renderizado de puntos de conocimiento y sesiones completas

db.py

schema + CRUD + FTS5(trigram, external-content), sin truncamiento

query.py

API de consulta orientada a llamadas

ingest.py

PDF → persistencia en base de datos (importación de directorio = reconstrucción completa, id reproducible)

exam_store.py

Base de datos SQLite independiente para calificaciones de tareas (CRUD; por defecto en iCloud Drive)

cli.py

Línea de comandos

server.py

Servicio HTTP (extra opcional)

mcp_server.py

Servicio MCP (extra opcional)

web/

Frontend de aprendizaje (Vite; ver más abajo «Frontend web de aprendizaje» y web/README.md)


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_FONTS en pdf_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_RULES en classify.py: asigna la clasificación temática según palabras clave del título.

  • Diccionario de palabras clave — TENSE_MARKERS en classify.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 8000

Tras 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

/stats

Estadísticas e información de metadatos del conjunto de datos

GET

/lectures

Lista de sesiones

GET

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

Contenido de una sesión (con tablas restauradas)

GET

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

Un punto de conocimiento

GET

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

Búsqueda de texto completo

GET

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

Palabras marcadoras

GET

/relation?type=主将从现

Consulta por relación

GET

/exam-signals

Todas las dimensiones de señales de examen

GET

/exam-signal?signal=时态

Búsqueda de puntos de conocimiento por señal de examen

GET

/vocabulary?limit=300&min_freq=2

Lista de vocabulario (definición/categoría gramatical/forma flexiva)

GET

/taxonomy

Árbol del sistema temático de puntos de conocimiento (categoría general → tema)

GET

/dict/{word}

Consulta de cualquier palabra (diccionario completo ECDICT)

GET/POST

/exams

Calificaciones de tareas: listar / añadir

PUT/DELETE

/exams/{id}

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:

  1. Variable de entorno GRAMMAR_KB_EXAM_DB

  2. iCloud 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 dispositivos

  3. Respaldo: 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-mcp

Herramientas 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:5180

Funciones:

  • 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 /exams del 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 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
      -