czsu MCP server sqlite

CZSU MCP SQLite云服务器

独立的FastMCP服务器使用SQLite Cloud为CZSU（捷克统计局）数据提供SQLite查询功能。

这是一个独立的FastMCP服务器，为CZSU多代理文本到SQL项目提供SQLite查询功能，使用 SQLite云 用于数据库托管。

特性

• FastMCP 2.0 采用原生MCP协议的框架

• 单一工具： sqlite_query 用于执行SQL查询

• SQLite云 数据库托管（不需要本地文件）

• SSE运输 用于远程访问

• 健康检查端点

• FastMCP云就绪（零配置）-使用 @mcp.tool() 工具定义的装饰器

• SSE运输 用于远程访问

快速入门-自动OpenAPI文档

• 内置健康检查端点

地方发展- FastMCP云就绪 -不需要特殊的配置文件！

# 1. Install dependencies

cd czsu_mcp_server_sqlite```

uv pip install .czsu_mcp_server_sqlite/

├── main.py              # FastMCP server implementation (entrypoint: main.py:mcp)

# 2. Copy database (if needed)├── pyproject.toml       # Python dependencies (preferred, auto-detected by FastMCP Cloud)

copy ..\data\czsu_data.db .\data\├── requirements.txt     # Python dependencies (legacy, for backward compatibility)

├── .env.example        # Environment variable template

# 3. Run server├── README.md           # This file

python main.py└── data/

服务器启动于 `http://localhost:8100`

## 地方发展设置

1. **安装依赖项：**

# Using uv (recommended - faster and better dependency resolution) uv pip install .

# Or using pip pip install .

1. **配置环境：**

# Copy and edit .env file copy .env.example .env # Edit .env with your SQLite Cloud connection string

1. **运行服务器：**

python main.py

服务器启动于 `http://localhost:8100`

### FastMCP云（推荐） **备注**：参见 `PACKAGE_MANAGEMENT.md` 有关依赖关系管理的详细指南。

1. 访问https://fastmcp.cloud3. **配置环境（可选）：**

1. 使用GitHub \`\`bash登录

1. 创建项目：#根据需要复制和编辑.env文件

   - **入口点**: `main.py:mcp` copy.env.example.env

   - **仓库**：您的GitHub仓库\`\`\`

1. 部署！

1. **在本地运行：**

您的服务器将位于： `https://your-project-name.fastmcp.app/mcp` \`\`\`bash

python main.py

看 [文档/部署.md](docs/DEPLOYMENT.md) 了解详情。   \`\`\`

## 结构服务器将启动于 `http://localhost:8100`

czsu_mcp_server_sqlite/

├── main.py # FastMCP server (entrypoint: main.py:mcp)FastMCP Cloud is the official managed platform for hosting MCP servers. It's free during beta!

├── pyproject.toml # Dependencies

├── .env.example # Environment template### Prerequisites

├── README.md # This file

├── docs/ # Documentation- GitHub account

│ ├── DEPLOYMENT.md- This folder in a GitHub repository (public or private)

│ └── PACKAGE_MANAGEMENT.md- Database file included in the repo

└── data/

└── czsu_data.db # SQLite database### Deployment Steps

1. **访问FastMCP云**首选https://fastmcp.cloud

## 配置

2. **使用GitHub登录**：验证您的GitHub帐户

环境变量（可选）：

3. **创建项目**:

PORT=8100 # Server port - Repository: Select your GitHub repo

DB_PATH=./data/czsu_data.db # Database path - Entrypoint: main.py:mcp (this is the FastMCP server object)

DEBUG=0 # Debug mode - Authentication: Enable or disable (your choice)

4. **部署**：FastMCP Cloud将自动：

## 依赖项

核心依赖关系：

- `fastmcp>=2.0.0` -MCP服务器框架
- `python-dotenv>=1.0.0` -环境变量
- `starlette>=0.45.0` -Web框架

数据库后端（根据需要安装）：

- `sqlitecloud>=0.0.80` -SQLite云连接(`pip install .[sqlitecloud]`)

- `libsql-client>=0.5.0` -Turso（libSQL）连接(`pip install .[turso]`)

## 文档https://your-project-name.fastmcp.app/mcp

• Deployment Guide: docs/DEPLOYMENT.md

• Package Management: 6. Update Main Project: In your main project's .env:

## Integration   MCP_SERVER_URL=https://your-project-name.fastmcp.app/mcp

USE_LOCAL_SQLITE_FALLBACK=1

This server is designed to work with the main CZSU Multi-Agent Text-to-SQL project.   ```

Configure main project's `.env`:### Auto-Deployment

MCP_SERVER_URL=https://your-project-name.fastmcp.app/mcp- Push changes to the main branch

USE_LOCAL_SQLITE_FALLBACK=1- Open a pull request (deploys preview version)

不需要CI/CD配置！

## 独立设计

## API终点

此文件夹具有 **无依赖关系** 在母项目上。所有导入都是自包含的，便于单独部署。

FastMCP服务器公开：

## 许可证

- **MCP协议端点** - `/mcp/v1/*` （由FastMCP自动创建）

CZSU多代理文本到SQL项目的一部分。-处理所有MCP协议操作

- 工具： `sqlite_query` -执行SQLite查询

- **健康检查** - `GET /health` （自定义路线）

  - 返回服务器和数据库状态
  - 可用于监控和正常运行时间检查

## FastMCP功能

- **类型安全工具定义** 使用Python装饰器
- **自动模式生成** 从函数签名
- **内置错误处理** 和验证
- **SSE运输** 用于基于web的部署
- **自定义路线** 用于其他端点（如健康检查）

## 安全说明

- 此服务器仅供内部使用
- 如果公开，请考虑添加身份验证
- 数据库是只读的（工具阻止修改）

## 环境变量

- `PORT` -服务器端口（默认值：8100）
- `DATABASE_TYPE` -数据库后端类型： `sqlitecloud` 或 `turso` （默认值：sqlitecloud）
- `SQLITE_CLOUD_CONNECTION_STRING` -SQLite云连接字符串（当DATABASE_TYPE=sqlitecloud时需要）
- `TURSO_CONNECTION_STRING` -Turso连接字符串（当DATABASE_TYPE=Turso时需要）
- `DEBUG` -启用调试日志记录（默认值：0）

## 测试

### 局部测试

1. **在本地启动服务器：**

python main.py

1. **测试健康终点：**

curl http://localhost:8100/health

1. **使用FastMCP客户端进行测试** （来自主项目）：

from fastmcp import Client

async def test_query(): async with Client("http://localhost:8100/mcp") as client: result = await client.call_tool("sqlite_query", { "query": "SELECT * FROM SELECTION LIMIT 5" }) print(result)

import asyncio asyncio.run(test_query())

### FastMCP云测试

部署后，使用与您的云URL相同的客户端代码：

async with Client("https://your-project-name.fastmcp.app/mcp") as client: # ... same as above

## 故障排除

### 地方发展问题

**服务器无法启动：**

- 检查Python版本（需要3.10+）
- 验证已安装的所有依赖项： `pip install -r requirements.txt`
- 检查端口8100是否可用
- 验证是否在中设置了SQLite Cloud连接字符串 `.env`

**数据库错误：**

- 检查SQLite Cloud连接字符串格式
- 验证API密钥是否有效
- 检查与SQLite Cloud的网络连接
- 确保数据库存在于您的SQLite Cloud帐户中

### FastMCP云部署问题

**构建失败：**

- 检查FastMCP Cloud日志中的错误消息
- 验证 `requirements.txt` 具有所有版本正确的依赖项
- 确保 `main.py` 出口 `mcp` 模块级对象
- 检查入口点是否准确： `main.py:mcp`

**服务器启动，但工具不起作用：**

- 检查SQLite Cloud连接字符串是否配置正确
- 验证数据库是否存在于SQLite Cloud帐户中
- 检查FastMCP Cloud日志是否存在运行时错误

**连接超时：**

- FastMCP Cloud可能正在冷启动（首次请求需要更长时间）
- 检查您的互联网连接
- 验证URL格式： `https://your-project-name.fastmcp.app/mcp`

**找不到工具：**

- 确保 `@mcp.tool()` 正确使用装饰器
- 检查函数是否异步(`async def`)
- 验证FastMCP版本是否为2.0或更高版本

### 获取帮助

- **FastMCP文档**: https://fastmcp.com/docs
- **FastMCP云支持**：联系方式https://fastmcp.cloud
- **MCP协议规范**: https://spec.modelcontextprotocol.io/

## 与主项目分离

此文件夹旨在 **移出** 作为一个独立的Git仓库进行维护。它不依赖于主项目的代码——所有导入都是自包含的。