AI导哈

SQLite数据库语义搜索服务

一个只读的MCP服务器，支持多SQLite数据库管理并提供可选的vec0语义搜索功能。

  • by bash0C7
  • Ruby
  • 本地部署
  • 更新于
在 GitHub 查看 bash0C7/chiebukuro-mcp

使用说明

首席执行官

用于多个SQLite数据库的只读MCP服务器，具有可选的vec0语义搜索功能。

每个数据库的工具名称来源于配置键：

  • chiebukuro_query_<db_name> --仅限SELECT/WITH（INSERT/UPDATE/DELETE/DROP被拒绝）
  • chiebukuro_semantic_search_<db_name> --通过vec0进行KNN矢量搜索（仅在以下情况下注册 semantic_search 配置存在）

配置

服务器读取 ~/chiebukuro-mcp/chiebukuro.json 在启动时。

{
  "databases": {
    "my_db": {
      "path": "/absolute/path/to/database.db",
      "description": "Description shown in the MCP tool",
      "semantic_search": {
        "vec_table": "memories_vec",
        "content_table": "memories",
        "content_column": "content",
        "source_column": "source",
        "join_key": "memory_id"
      }
    }
  }
}

semantic_search 是可选的。对于没有vec0表的数据库，省略它。

检查数据库

使用 inspect 用于为任何SQLite数据库生成建议配置项的子命令：

bundle exec exe/chiebukuro-mcp inspect /path/to/database.db

输出包括 suggested_config 自动检测 semantic_search 如果找到vec0表，则进行设置。

集成

服务器通过以下方式启动 scripts/start_mcp.sh，它明确使用rbenv的bundler来避免系统与Ruby的冲突。

克劳德代码 --添加到 ~/.claude/settings.json:

"mcpServers": {
  "chiebukuro-mcp": {
    "type": "stdio",
    "command": "/path/to/chiebukuro-mcp/scripts/start_mcp.sh"
  }
}

克劳德桌面版 --添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

"mcpServers": {
  "chiebukuro-mcp": {
    "command": "/path/to/chiebukuro-mcp/scripts/start_mcp.sh"
  }
}

~/chiebukuro-mcp/chiebukuro.json 开始前必须存在--请参阅 配置 格式见上文。请将其保存在您的点文件中，而不是此存储库中。

试剂就绪的MCP表面

对于每个已配置的数据库，服务器现在除了公开 chiebukuro_query_<db> 和 chiebukuro_semantic_search_<db>:

  • chiebukuro_explain_query_<db> --跑步 EXPLAIN QUERY PLAN 针对只读SELECT。
  • chiebukuro_query_with_clarification_<db> --自然语言意图驱动。使用MCP启发来填充插槽，然后执行配方模板。如果数据库没有配方，则返回到简单的查询指导。
  • schema://<db> --表和列的Markdown描述。
  • recipes://<db> --带有解释注释的配方查询模板的Markdown目录。
  • hints://<db> --列枚举值/样本值/注释规则的Markdown目录。

加上一个全球工具：

  • chiebukuro_probe_capabilities --报告连接的MCP主机是否声明 sampling 和 elicitation 能力。

预填澄清参数

chiebukuro_query_with_clarification_<db> 暴露每一个 clarification_field 从DB的yml作为 顶级可选参数 工具本身。主机LLM（例如Claude Code）可以根据用户的自然语言意图预填充其中的任何一个，通常是根据当前日期解析的日期，或者 source_like 它映射到已知来源的模式，只有尚未解决的槽才能通过启发。

工具描述会自动添加前缀 [Agent usage] 提示告诉代理：

  • 解析日期表达式（今天/星期/今天/月/最近/N日前 / 具体日期）与当前日期进行比较，并将其作为日期参数传递。
  • 不预填充具有yml级别的插槽 default （通常 limit)除非用户明确要求特定计数，否则这些计数将在服务器端默默解决。

内部决议优先级 IntentAnalyzer:

  1. prefilled （主机LLM→ 刀具参数）--最高
  2. 意图字符串上的关键字匹配（通过 clarification_fields[].hints.keywords)
  3. yml字段级别 default
  4. 否则：留在 missing_fields 并通过启发式形式提问

skip_if_resolved: true （默认）从启发表单中删除任何已解析的槽，因此预填充是主持人避免打扰用户的方式。

工具的 input_schema 动态构建自 clarification_fields，因此向yml+重新运行添加插槽 apply_meta_patches.rb 就足够了——不需要更改服务器代码。

_sqlite_mcp_meta 扩展模式

每个DB都可以自我描述。 _sqlite_mcp_meta 有以下列：

列 使用人 目的
object_type 全部 'db' / 'table' / 'column' / 'recipe' / 'clarification_field'
object_name all 目标名称（列使用 'table.column'，食谱/插槽使用标签）
description 所有 人类可读文本
hints_json column, clarification_field JSON格式 enum_values, sample_values, related_tables, note，或插槽属性
recipe_sql recipe SELECT/WITH模板，命名占位符 :key 允许
recipe_label recipe 短显示标签

只有3列的旧式DB(object_type, object_name, description)桌子继续工作； MetaReader 默默地为它们返回空的食谱/提示。

优雅降级

如果数据库没有配方和clarification_fields，服务器：

  1. 将启动警告记录到stderr。
  2. 仍然注册所有工具和资源。
  3. query_with_clarification 短路和回流 fallback 告诉来电者开车的动作 chiebukuro_query_<db> / chiebukuro_semantic_search_<db> 直接使用 schema://<db> 为了定向。

配方/提示数据本身是在这个仓库之外管理的——请参见 dotfiles/chiebukuro-mcp/scripts/meta_patches/*.yml.

结构化呼叫日志（stderr）

每个MCP工具调用都会向stderr发出一行JSON条目，以便主机端日志使用者可以在不接触存储库的情况下审核路由决策和工具选择。

例子：

{"ts":"2026-04-18T11:01:08+09:00","kind":"tool_call","tool":"chiebukuro_query_health","db":"health","result_rows":7,"elapsed_ms":42}

领域：

  • ts --ISO8601调用开始（JST）。
  • kind — tool_call （保留给未来的种类，如 resource_read).
  • tool --MCP工具的完整名称。
  • db --目标数据库名称，或 - 对于独立于数据库的工具（例如。 chiebukuro_probe_capabilities).
  • result_rows --响应中的尽力行数（解析失败时为0）。
  • elapsed_ms --整数毫秒。

JSON行({ 前缀）与现有的人类可读启动警告脱节([chiebukuro-mcp] ..., [ 前缀），所以下游 grep / jq 可以按第一个字符将其拆分。

这纯粹是累加性的——没有MCP协议的影响，也没有对工具结果的改变。

发展

bundle config set --local path vendor/bundle
bundle install
bundle exec rake test

相关 MCP