generic database metadata MCP

GlossaryWeaver

A. 节能、节省上下文的元数据MCP服务器 由...支持 FalkorDBLite （轻量级嵌入式FalkorDB图形引擎），具有 只读可视化web仪表板.

服务器展示了一个类型化元数据对象的图，这些对象的边承载着生命 confidence_score。每次穿过边缘时，边缘都会得到加强，如果不使用，边缘会腐烂——体现了蚁群激励的“使用或丢失”原则。MCP工具响应使用紧凑型 卡通 序列化格式，以保持LLM上下文窗口较小。仪表板绕过TOON，向浏览器提供完整的JSON（规则3.6豁免）。

实施说明：图形后端是 FalkorDBLite --FalkorDB的轻量级嵌入式版本，在单个Docker容器内运行，没有集群开销。Python包是 falkordb；当连接到独立的Docker实例时，轻量级模式会自动激活。

______________________________________________________________________

建筑

src/
├── graph/
│   ├── client.py        # FalkorDB connection singleton
│   ├── ontology.py      # MetaType CRUD + health-score management
│   ├── nodes.py         # ObjectNode CRUD + bulk ingest
│   ├── edges.py         # StigmergicEdge CRUD, reinforce, decay, cascading wither
│   ├── decay.py         # Decay runner (single edge + full-graph sweep)
│   ├── query.py         # Bounded traversal (1-2 hops) + flat scan + pagination
│   └── schema.py        # Graph schema helpers
├── dashboard/           # Visual web dashboard API (FastAPI, port 8080)
│   ├── api.py           # App factory; mounts static files; /health + /api/graph + /api/health
│   ├── auth.py          # JWT Bearer decode; DashboardUser dependency; 401/403
│   ├── router.py        # GET /api/graph route (scoped, read-only)
│   ├── health_router.py # GET /api/health/meta-types — USL enforced at constructor level
│   ├── health_service.py# HealthService: colour-band computation, DASHBOARD_NODE_LIMIT cap
│   ├── security.py      # Unified Security Layer: derive_session_id, AuditService, unified_security
│   ├── graph_service.py # DashboardGraphService — wraps query.py; 500-node cap
│   ├── models.py        # Pydantic response models (GraphNodeResponse, HealthPayloadResponse, ...)
│   ├── config.py        # Env-var loading (DASHBOARD_JWT_SECRET, DASHBOARD_PORT, ...)
│   └── server.py        # uvicorn entrypoint (port 8080)
├── models/
│   ├── base.py          # Pydantic models for all graph entities
│   ├── dynamic.py       # Runtime model factory (pydantic.create_model)
│   └── serialization.py # TOON compact serialiser / paginator
├── mcp_server/
│   ├── app.py           # FastMCP singleton
│   ├── server.py        # Entry point — registers all tools, calls mcp.run()
│   ├── formatters/
│   │   └── toon.py      # TOON compact format helpers
│   └── tools/
│       ├── ingestion.py # insert_node, bulk_ingest_seed (circuit breaker)
│       ├── ontology.py  # register_meta_type, list_meta_types_tool
│       ├── stigmergy.py # create_stigmergic_edge, reinforce_stigmergic_edge
│       ├── query.py     # query_graph
│       ├── lifecycle.py # deprecate_node, branch_node_for_domain, request/confirm deletion
│       ├── healing.py   # suggest_schema_heals, confirm_schema_heal
│       └── functions.py # create_function, query_functions, attach_function_to_nodes
└── utils/
    ├── logging.py       # Logger + error class hierarchy
    └── context.py       # RequestContext (profile, domain, prompt hash, session)

dashboard/               # Frontend static assets (served by the dashboard API)
├── index.html           # Single-page app shell; loads Cytoscape.js 3.x from CDN
├── app.js               # Canvas render, node click/dim, filter panel, search, edge tooltips,
│                        #   schema health panel (colour-band indicators, refresh, degraded state)
└── style.css            # Full-height dark-theme layout; confidence_score edge encoding;
                         #   health indicator colour classes (.health-green/amber/red)

scripts/
└── bootstrap_indices.py # Create FalkorDB indices on HumanAuditLog (profile_id, timestamp)

tests/
├── conftest.py
├── unit/
│   ├── dashboard/
│   │   ├── test_auth.py              # JWT auth (401/403, expired, missing claims)
│   │   ├── test_graph_service.py     # Scope enforcement, 500-node cap, confidence clamp
│   │   ├── test_health_service.py    # Health band boundaries, truncation, error handling
│   │   ├── test_unified_security.py  # USL: derive_session_id, audit write, 401/403/503
│   │   └── test_performance.py       # SC-002 serialisation 
   cd generic_database_metadata_mcp

   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # macOS / Linux
   source .venv/bin/activate

   pip install -r requirements.txt

1. Bootstrap FalkorDBLite索引 （仅限首次运行）：

   python scripts/bootstrap_indices.py

______________________________________________________________________

运行MCP服务器

继续运行 http://127.0.0.1:8000 （苏格兰和南方能源公司运输）。

python -m src.mcp_server.server

预期日志输出：

INFO: src.graph.client: Connecting to FalkorDBLite at localhost:6379
INFO: src.mcp_server.server: [FastMCP] MCP tools registered: 17
INFO: uvicorn.server: Uvicorn running on http://127.0.0.1:8000

______________________________________________________________________

运行可视化仪表板

继续运行 http://127.0.0.1:8080 作为 独立过程。需要 DASHBOARD_JWT_SECRET 有人是。

export DASHBOARD_JWT_SECRET="your-secret-here"
python -m src.dashboard.server

打开 http://localhost:8080 在浏览器中，粘贴一个有效的JWT，元数据图会自动呈现。

仪表板环境变量

______________________________________________________________________

仪表板功能

US1--交互式图形画布

经过身份验证的用户允许范围内的节点在3秒内呈现为平移/缩放Cytoscape.js画布。单击节点以打开属性侧面板并调暗非相邻节点。按Esc或单击背景进行还原。

US2--污名化与结构性边缘

耻辱边缘编码 confidence_score 作为线宽（0.0时为1像素->1.0时为6像素）。低于0.2的边渲染为虚线并弱化。结构边缘是一条固定的1.5像素实灰线。将鼠标悬停在任意边上以显示工具提示——刺激能量工具提示包括 confidence_score, rationale_summary，以及 last_accessed.

US3--筛选和搜索

从过滤器面板中选择一个或多个对象类型以限制可见节点。类型a business_name 子字符串用于对不匹配的节点进行暗淡处理，并自动将中心对准连接最紧密的匹配。刷新按钮可重置两者。

US4--配置文件感知范围视图

每个API请求都需要JWT轴承 profile_id 和 domain_scope.Domain作用域是在服务器端对每个查询强制执行的——不可能发生跨域数据泄漏。缺少令牌->HTTP 401；缺少声明->HTTP 403。

US5--模式健康小部件

可折叠的健康面板显示用户范围内的每个MetaType，按以下方式排序 health_score 上升（首先是不健康的）。每行显示一个颜色编码的指示器（绿色>=0.8，琥珀色>=0.5，红色\ cs, name -> n等等）

• 默认值/空值被删除
• 硬上限：每个响应有效负载10 KB
• 分页信封： {"items": [...], "total": N, "page": P, "has_more": bool}

仪表板API是 明确豁免 根据规则3.6，从TOON开始，它向浏览器提供完整的JSON。

______________________________________________________________________

耻辱的衰败

一旦超过24小时的访问阈值，边缘就会随着时间的推移被动衰减（0.05/天）。边缘 confidence_score 降至以下 0.1 自动修剪。随时运行完整的衰变扫描：

from src.graph.decay import run_all_decay
result = run_all_decay()
# {"processed": 42, "pruned": 3}

______________________________________________________________________

测试

# All tests (requires FalkorDB running)
pytest tests/ -v

# Dashboard tests only (no live FalkorDB needed)
pytest tests/unit/dashboard/ tests/contract/ tests/integration/test_dashboard_api.py -v

仪表板测试使用FastAPI TestClient 使用猴痘匹配的服务方法——不需要实时的FalkorDB。所有其他测试都使用一个名为FalkorDB的临时随机图，该图在完成时被拆除。 freezegun 用于模拟衰变断言的时间传递。

______________________________________________________________________

过梁和类型检查

ruff check src/ tests/
mypy src/