Looper Game Chatbot MCP

MCP MariaDB 服务器

MCP MariaDB服务器提供了一个模型上下文协议（MCP）接口，用于管理和查询MariaDB数据库，支持标准SQL操作以及基于高级向量/嵌入的搜索。该接口专为与AI助手配合使用而设计，能够实现由AI驱动的数据工作流程与关系型数据库和向量数据库的无缝集成。

______________________________________________________________________

目录

• 概述
• 核心组件
• 可用工具
• 嵌入表示与向量存储
• 配置与环境变量
• 安装与设置
• 使用示例
• 集成 - Claude桌面版/Cursor/Windsurf
• 记录日志
• 测试

______________________________________________________________________

概述

MCP MariaDB Server 提供了一组工具，通过标准化协议与 MariaDB 数据库和向量存储进行交互。它支持：

• 列出数据库和表
• 检索表架构
• 执行安全的、只读的SQL查询
• 创建和管理用于基于嵌入的搜索的向量存储
• 与嵌入服务提供商集成（当前支持OpenAI、Gemini和HuggingFace）（可选）

______________________________________________________________________

核心组件

• server.py（服务器文件）主要的MCP服务器逻辑和工具定义。
• config.py（配置文件）从环境加载配置并 .env 文件。
• \embeddings.py\ 翻译成中文是“嵌入.py”负责处理嵌入服务集成（OpenAI）。
• 测试/手动和自动化测试文档及脚本。

______________________________________________________________________

可用工具

标准数据库工具

• 列出数据库

- 列出所有可访问的数据库。 - 参数： _无_

• 列出表

- 列出指定数据库中的所有表。 - 参数： database_name （字符串，必填）

• 获取表结构

- 检索表的模式（列、类型、键等）。 - 参数： database_name （字符串，必填）， table_name （字符串，必填）

• 获取带有关系的表模式

- 检索包含外键关系的表模式。 - 参数： database_name （字符串，必填）， table_name （字符串，必填）

• 执行SQL

- 执行一个只读的SQL查询（SELECT， SHOW， DESCRIBE）。 - 参数： sql_query (字符串，必填)， database_name （字符串，可选）， parameters （列表，可选） - _注：如果满足条件，则强制启用只读模式 MCP_READ_ONLY 已启用。_

• 创建数据库

- 如果数据库不存在，则创建一个新数据库。 - 参数： database_name （字符串，必填）

向量存储与嵌入工具（可选）

注这些工具仅在以下情况下可用： EMBEDDING_PROVIDER 已配置。如果未设置嵌入式服务提供商，这些工具将被禁用。

• 创建向量存储

- 为嵌入创建一个新的向量存储（表）。 - 参数： database_name， vector_store_name， model_name （可选）， distance_function （可选，默认：余弦）

• 删除向量存储

- 删除一个向量存储（表）。 - 参数： database_name， vector_store_name

• 列表矢量存储

- 列出数据库中的所有向量存储。 - 参数： database_name

• 插入文档向量存储

- 将文档（和可选的元数据）批量插入到向量存储中。 - 参数： database_name， vector_store_name， documents （字符串列表）， metadata （可选的字典列表）

• 搜索向量存储

- 使用嵌入技术对相似文档执行语义搜索。 - 参数： database_name， vector_store_name， user_query (字符串)， k （可选，默认值：7）

______________________________________________________________________

嵌入表示与向量存储

概述

MCP MariaDB 服务器提供 可选的 嵌入和向量存储功能。这些功能可以通过配置一个嵌入提供商来启用，或者如果您只需要标准的数据库操作，则可以完全禁用它们。

支持的提供者

• OpenAI（开放人工智能研究所）
• 双子座
• 从Huggingface打开模型

配置

• EMBEDDING_PROVIDER设置为 openai， gemini， huggingface，或保持未设置以禁用
• OPENAI_API_KEY如果使用OpenAI嵌入，则为必填项
• GEMINI_API_KEY如果使用Gemini嵌入，则此为必填项
• HF_MODEL如果使用HuggingFace嵌入模型（例如“intfloat/multilingual-e5-large-instruct”或“BAAI/bge-m3”），则此为必需项

模型选择

• 默认模型和允许模型可以在代码中进行配置（DEFAULT_OPENAI_MODEL， ALLOWED_OPENAI_MODELS）
• 模型可根据请求选择，或默认使用配置的模型

向量存储架构

向量存储表包含以下列：

• id自增主键
• document文件正文
• embedding向量类型（为相似性搜索建立索引）
• metadataJSON（可选元数据）

______________________________________________________________________

配置与环境变量

所有配置均通过环境变量进行（通常在 .env 文件)：

以下是根据您提供的信息翻译的内容： GEMINI_API_KEY | OpenAI嵌入的API密钥 | 是（如果EMBEDDING_PROVIDER=openai） | | HF_MODEL |

以下是根据您提供的信息翻译后的内容： .env

| Gemini嵌入的API密钥 | 是（如果EMBEDDING_PROVIDER=gemini） | |

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database

MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
HF_MODEL="BAAI/bge-m3"

|

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database
MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

______________________________________________________________________

| 从Huggingface打开模型 | 是（如果EMBEDDING_PROVIDER=huggingface） | |

示例

• 文件 支持嵌入（OpenAI）： .python-version不支持嵌入：
• 安装与设置 要求 Python 3.11(见
• ）

紫外线

1. （依赖管理器；

1. 安装说明 uv )

   pip install uv

1. MariaDB 服务器（本地或远程）

   uv pip compile pyproject.toml -o uv.lock

   uv pip sync uv.lock

1. 步骤 .env 克隆仓库 安装（如果尚未）：

1. 安装依赖项

创造

   python server.py

在项目根目录（参见

   python server.py --transport sse --host 127.0.0.1 --port 9001

配置

   python server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp

______________________________________________________________________

)

运行服务器

{
  "tool": "execute_sql",
  "parameters": {
    "database_name": "test_db",
    "sql_query": "SELECT * FROM users WHERE id = %s",
    "parameters": [123]
  }
}

标准输入/输出（默认）：

{
  "tool": "create_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "model_name": "text-embedding-3-small",
    "distance_function": "cosine"
  }
}

SSE 交通（或：SSE 运输部门）

{
  "tool": "insert_docs_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "documents": ["Sample text 1", "Sample text 2"],
    "metadata": [{"source": "doc1"}, {"source": "doc2"}]
  }
}

HTTP传输（可流式传输的HTTP）：

{
  "tool": "search_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "user_query": "What is the capital of France?",
    "k": 5
  }
}

______________________________________________________________________

使用示例

标准SQL查询

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mariadb-mcp-server/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

创建向量存储

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/sse",
      "type": "sse"
    }
  }
}

将文档插入向量存储

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/mcp",
      "type": "streamable-http"
    }
  }
}

______________________________________________________________________

语义搜索

• 集成 - Claude桌面版/Cursor/Windsurf/VSCode logs/mcp_server.log 选项1：直接命令（标准输入输出）
• 选项2：SSE传输
• 选项3：HTTP传输 config.py 记录日志

______________________________________________________________________

日志被写入到

• 默认情况下。 src/tests/ 日志消息包括工具调用、配置问题、嵌入错误以及客户端请求。
• 日志级别和输出可以在代码中进行调整（参见 src/tests/README.md 以及日志记录器的设置）。
• 测试