使用说明

MCP SQL/API服务器

生产准备就绪 模型上下文协议（MCP） C#中的服务器实现。NET 8，它为HTTP API集成和SQL Server数据库操作提供了强大的工具。专为需要通过AI代理和自动化系统进行安全、类型安全数据访问的企业应用程序而设计。

📋 目录

概述
特性
先决条件
入门指南
测试指导
整合
配置
API 参考
安全
故障排除
贡献
许可证

概述

MCP SQL/API服务器弥补了人工智能系统和企业数据源之间的差距，实现了对以下内容的安全编程访问：

HTTP/REST API：使用可配置的安全策略向外部服务发出经过身份验证的请求
SQL Server数据库：执行带有内置防注入功能的参数化查询和命令

架构：

┌─────────────────────┐
│   MCP Client        │
│ (Claude, mini-AGI)  │
└──────────┬──────────┘
           │ JSON-RPC 2.0
           │ (stdio/HTTP)
┌──────────▼──────────┐
│  MCP Server         │
│  (This Project)     │
├─────────────────────┤
│ • HTTP Tool Service │──► External APIs
│ • SQL Tool Service  │──► SQL Server
└─────────────────────┘

特性

🌐 HTTP API工具(`http.call`)

执行具有企业级安全性的HTTP请求：

方法：获取、发布、放置、删除、补丁、头部、选项
认证：自定义标头支持（承载令牌、API密钥）
查询参数：动态参数注入
请求体：JSON序列化
安全：主机分配，可配置超时
错误处理：具有重试逻辑的结构化错误响应

🗄️ SQL Server工具

使用多个安全层保护数据库操作：

sql.query：执行具有行限制的SELECT查询
sql.execute：使用审计跟踪执行INSERT、UPDATE、DELETE

安全功能：

✅ 参数化查询执行
✅ DDL操作阻塞（DROP、TRUNCATE、ALTER）
✅ 查询超时限制
✅ 最大行返回限制
✅ SQL注入预防
✅ 交易支持

🔧 双重运输模式

标准运输 （默认）：生产就绪MCP协议
HTTP传输：使用REST端点进行测试和监控

先决条件

在开始之前，请确保已安装以下内容：

需求	版本	目的	下载
.NET SDK	8.0+	运行时和构建工具	下载
SQL Server	2019+	数据库（仅HTTP可选）	下载
Git	最新版本	源代码管理	下载

可选工具：

Visual Studio 2022/VS代码/JetBrains Rider
Docker桌面（用于SQL Server容器）
curl或Postman（用于HTTP测试）

验证先决条件：

# Check .NET SDK
dotnet --version
# Expected output: 8.0.x or higher

# Check Git
git --version
# Expected output: git version 2.x.x

入门指南

按照以下步骤使MCP服务器在本地计算机上运行。

步骤1：克隆和构建

1.1克隆存储库

git clone https://github.com/b9b4ymiN/mcp.NET.git
cd mcp.NET

1.2验证存储库结构

ls -la
# You should see: src/, CLAUDE.md, README.md, etc.

1.3恢复依赖关系

dotnet restore

预期产量：

Determining projects to restore...
Restored /path/to/mcp.NET/src/Mcp.SqlApiServer/Mcp.SqlApiServer.csproj
Restore succeeded.

1.4建设项目

dotnet build

预期产量：

Build succeeded.
    0 Warning(s)
    0 Error(s)

✅ 验证：

# Check if build artifacts exist
ls src/Mcp.SqlApiServer/bin/Debug/net8.0/
# Should contain: Mcp.SqlApiServer.dll, Mcp.SqlApiServer.exe (Windows), etc.

步骤2：配置SQL Server

选择以下配置方法之一：

选项A：使用用户机密（建议用于开发）

2.1初始化用户密码

cd src/Mcp.SqlApiServer
dotnet user-secrets init

2.2设置连接字符串

# For local SQL Server
dotnet user-secrets set "Sql:ConnectionString" "Server=localhost;Database=TestDb;User Id=sa;Password=YourPassword;Encrypt=False;TrustServerCertificate=True"

# For Azure SQL
dotnet user-secrets set "Sql:ConnectionString" "Server=tcp:yourserver.database.windows.net,1433;Database=TestDb;User Id=username;Password=password;Encrypt=True"

2.3返回根目录

cd ../..

选项B：使用Docker SQL Server（最快）

2.1启动SQL Server容器

docker run -e "ACCEPT_EULA=Y" \
  -e "SA_PASSWORD=YourStrong@Passw0rd123" \
  -p 1433:1433 \
  --name mcp-sqlserver \
  -d mcr.microsoft.com/mssql/server:2022-latest

2.2等待SQL Server启动

# Wait 10-15 seconds for SQL Server initialization
sleep 15

2.3配置连接字符串

cd src/Mcp.SqlApiServer
dotnet user-secrets set "Sql:ConnectionString" "Server=localhost,1433;Database=master;User Id=sa;Password=YourStrong@Passw0rd123;Encrypt=False;TrustServerCertificate=True"
cd ../..

选项C：使用环境变量

2.1设置环境变量

# Linux/macOS
export Sql__ConnectionString="Server=localhost;Database=TestDb;User Id=sa;Password=YourPassword;Encrypt=False"

# Windows PowerShell
$env:Sql__ConnectionString="Server=localhost;Database=TestDb;User Id=sa;Password=YourPassword;Encrypt=False"

# Windows CMD
set Sql__ConnectionString=Server=localhost;Database=TestDb;User Id=sa;Password=YourPassword;Encrypt=False

✅ 验证：

# Test SQL connection (will try to start server)
dotnet run --project src/Mcp.SqlApiServer http
# If connection string is valid, server will start
# Press Ctrl+C to stop

步骤3：配置HTTP安全

3.1打开配置文件

# Edit the development settings
nano src/Mcp.SqlApiServer/appsettings.Development.json
# Or use your preferred editor: code, vim, etc.

3.2添加允许的主机

编辑 HttpTool 部分包括您要允许的主机：

{
  "HttpTool": {
    "AllowedHosts": [
      "api.github.com",
      "jsonplaceholder.typicode.com",
      "httpbin.org",
      "localhost",
      "127.0.0.1"
    ],
    "DefaultTimeoutSeconds": 30,
    "MaxTimeoutSeconds": 120,
    "AllowAllHosts": false
  }
}

3.3安全注意事项

⚠️ 重要安全设置：

AllowAllHosts: false -在生产中保持禁用状态
仅将受信任的主机添加到 AllowedHosts
主机不区分大小写
子域名不会自动包含在内

✅ 验证：

# Check configuration file syntax
cat src/Mcp.SqlApiServer/appsettings.Development.json | grep -A 5 "HttpTool"
# Should display your HttpTool configuration

步骤4：运行服务器

在标准模式下运行（默认-生产）

4.1启动服务器

dotnet run --project src/Mcp.SqlApiServer

4.2预期产量

info: Program[0]
      MCP SQL/API Server v1.0.0
info: Program[0]
      Transport mode: STDIO (standard MCP protocol)
info: Program[0]
      Tip: Run with 'http' argument or MCP_TRANSPORT_MODE=http for HTTP mode
info: Mcp.SqlApiServer.Infrastructure.McpServer[0]
      MCP Server starting. Reading from stdin...

4.3服务器已就绪

服务器现在正在等待stdin上的JSON-RPC输入。保持这个终端打开。

✅ 测试连接（在另一个终端中）：

# Send initialize request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | dotnet run --project src/Mcp.SqlApiServer

# Expected: JSON response with server info

在HTTP模式下运行（测试/开发）

4.1启动HTTP服务器

dotnet run --project src/Mcp.SqlApiServer http

4.2预期产量

info: Program[0]
      Starting MCP SQL/API Server in HTTP mode on port 5000
info: Program[0]
      Endpoints:
info: Program[0]
        - GET  /tools       - List all available tools
info: Program[0]
        - GET  /health      - Health check
info: Program[0]
        - POST /mcp         - MCP Inspector compatible endpoint
info: Program[0]
        - POST /tools/{name} - Execute specific tool
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://0.0.0.0:5000

4.3自定义端口（可选）

# Set custom port
export MCP_HTTP_PORT=8080
dotnet run --project src/Mcp.SqlApiServer http

✅ 验证：

# Test health endpoint
curl http://localhost:5000/health

# Expected output:
# {
#   "status": "healthy",
#   "server": "mcp-sqlapi-server",
#   "version": "1.0.0",
#   "timestamp": "2024-01-15T10:30:00Z"
# }

测试指导

完成测试所有服务器功能的分步指南。

使用HTTP模式进行测试

这是初始测试和开发的推荐方法。

测试1：服务器健康检查

目的： 验证服务器是否正常运行

步骤：

# 1. Start server in HTTP mode (if not already running)
dotnet run --project src/Mcp.SqlApiServer http

# 2. In another terminal, check health
curl http://localhost:5000/health

预期结果：

{
  "status": "healthy",
  "server": "mcp-sqlapi-server",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

✅ 成功标准： 状态为“健康”

测试2：列出可用工具

目的： 验证所有工具是否已注册

步骤：

curl http://localhost:5000/tools | jq

预期结果：

{
  "tools": [
    {
      "name": "http.call",
      "description": "Make HTTP requests to external APIs...",
      "inputSchema": { ... }
    },
    {
      "name": "sql.query",
      "description": "Execute SELECT queries on SQL Server...",
      "inputSchema": { ... }
    },
    {
      "name": "sql.execute",
      "description": "Execute INSERT, UPDATE, DELETE statements...",
      "inputSchema": { ... }
    }
  ],
  "count": 3
}

✅ 成功标准： 计数为3，所有工具名称都存在

测试3:HTTP API工具

目的： 测试外部HTTP请求

3.1简单GET请求：

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.github.com/users/octocat"
  }' | jq

预期结果：

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json; charset=utf-8",
    ...
  },
  "bodyText": "{\"login\":\"octocat\",\"id\":583231,...}"
}

✅ 成功标准： 状态代码为200

3.2带查询参数的GET：

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.github.com/users/octocat/repos",
    "query": {
      "per_page": 3,
      "sort": "updated"
    }
  }' | jq '.statusCode'

预期结果： 200

3.3使用JSON正文进行POST：

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "url": "https://httpbin.org/post",
    "body": {
      "name": "Test User",
      "email": "test@example.com"
    }
  }' | jq '.statusCode'

预期结果： 200

3.4测试主机阻塞（安全）：

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://blocked-site.com/api"
  }' | jq

预期结果：

{
  "error": "Host 'blocked-site.com' is not in the allowed hosts list..."
}

✅ 成功标准： 请求被阻止，并显示相应的错误消息

测试4:SQL查询工具

目的： 测试数据库SELECT操作

4.1简单查询：

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT @@VERSION AS SqlVersion, GETDATE() AS CurrentTime"
  }' | jq

预期结果：

{
  "rows": [
    {
      "SqlVersion": "Microsoft SQL Server 2022...",
      "CurrentTime": "2024-01-15T10:30:00"
    }
  ],
  "rowCount": 1
}

✅ 成功标准： 返回服务器版本和时间戳

4.2参数化查询：

首先，创建一个测试表（使用sql.sexecute）：

# Create test table
curl -X POST http://localhost:5000/tools/sql.execute \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "IF NOT EXISTS (SELECT * FROM sys.tables WHERE name = '\''TestUsers'\'') CREATE TABLE TestUsers (Id INT PRIMARY KEY IDENTITY, Name NVARCHAR(100), Status NVARCHAR(50))"
  }'

# Insert test data
curl -X POST http://localhost:5000/tools/sql.execute \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "INSERT INTO TestUsers (Name, Status) VALUES (@Name, @Status)",
    "parameters": {
      "@Name": "John Doe",
      "@Status": "active"
    }
  }'

然后用参数查询：

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM TestUsers WHERE Status = @Status",
    "parameters": {
      "@Status": "active"
    }
  }' | jq

预期结果：

{
  "rows": [
    {
      "Id": 1,
      "Name": "John Doe",
      "Status": "active"
    }
  ],
  "rowCount": 1
}

4.3测试安全-阻止非选择：

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "DELETE FROM TestUsers"
  }' | jq

预期结果：

{
  "error": "sql.query only accepts SELECT statements. Use sql.execute for INSERT/UPDATE/DELETE."
}

✅ 成功标准： DELETE被阻止，并出现相应错误

4.4测试安全-阻止DDL：

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "DROP TABLE TestUsers"
  }' | jq

预期结果：

{
  "error": "DDL operations (DROP, TRUNCATE, ALTER, CREATE, etc.) are not allowed."
}

✅ 成功标准： DROP被阻止

测试5:SQL执行工具

目的： 测试数据库修改操作

5.1插入：

curl -X POST http://localhost:5000/tools/sql.execute \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "INSERT INTO TestUsers (Name, Status) VALUES (@Name, @Status)",
    "parameters": {
      "@Name": "Jane Smith",
      "@Status": "pending"
    }
  }' | jq

预期结果：

{
  "rowsAffected": 1
}

5.2更新：

curl -X POST http://localhost:5000/tools/sql.execute \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "UPDATE TestUsers SET Status = @NewStatus WHERE Name = @Name",
    "parameters": {
      "@NewStatus": "active",
      "@Name": "Jane Smith"
    }
  }' | jq

预期结果：

{
  "rowsAffected": 1
}

5.3删除：

curl -X POST http://localhost:5000/tools/sql.execute \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "DELETE FROM TestUsers WHERE Status = @Status",
    "parameters": {
      "@Status": "pending"
    }
  }' | jq

预期结果：

{
  "rowsAffected": 0
}

（0，因为我们刚刚将Jane更新为“活动”）

✅ 成功标准： 所有操作均已成功完成

MCP检验员测试

MCP Inspector为测试提供了一个可视化界面。

方法1:HTTP连接（推荐）

步骤1：启动服务器

dotnet run --project src/Mcp.SqlApiServer http

步骤2：打开MCP检查器

访问：https://inspector.modelcontextprotocol.io
或者在本地运行： npx @modelcontextprotocol/inspector

步骤3：连接

从下拉列表中选择“HTTP传输”
输入URL: http://localhost:5000/mcp
点击“连接”

步骤4：预期状态

连接状态：✅ 连接
显示的服务器信息：“mcp-sqlapi-Server v1.0.0”
工具列表显示3个工具

步骤5：测试工具

点击工具列表中的“http.call”
填写参数：
- 方法： GET
- 网址： https://api.github.com/users/octocat
点击“执行”
在输出面板中查看响应

✅ 成功标准： 状态为200的响应显示

方法2：标准连接

步骤1：使用Stdio运行检查器

npx @modelcontextprotocol/inspector dotnet run --project src/Mcp.SqlApiServer

第二步：预期产出

检查器在浏览器中打开
服务器自动连接
工具已列出

步骤3：测试工具 与方法1相同，步骤4-5

测试单个工具

每个工具的完整测试套件：

HTTP调用工具测试套件

测试1：基本GET

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{"method":"GET","url":"https://httpbin.org/get"}' \
  | jq '.statusCode'
# Expected: 200

测试2:POST与身体

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "url": "https://httpbin.org/post",
    "body": {"test": "data"}
  }' | jq '.statusCode'
# Expected: 200

测试3：自定义标头

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://httpbin.org/headers",
    "headers": {
      "X-Custom-Header": "TestValue",
      "Authorization": "Bearer test-token"
    }
  }' | jq
# Expected: Headers should appear in response

测试4：超时

curl -X POST http://localhost:5000/tools/http.call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://httpbin.org/delay/2",
    "timeoutSeconds": 5
  }' | jq '.statusCode'
# Expected: 200

SQL查询工具测试套件

测试1：系统信息

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT @@SERVERNAME AS ServerName, DB_NAME() AS DatabaseName"
  }' | jq '.rows'
# Expected: Server and database information

测试2：多行

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT TOP 5 name, type_desc FROM sys.objects ORDER BY name"
  }' | jq '.rowCount'
# Expected: 5

测试3：空值

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT NULL AS NullValue, '\''Text'\'' AS TextValue"
  }' | jq
# Expected: Properly handle NULL

SQL执行工具测试套件

测试1：创建表

curl -X POST http://localhost:5000/tools/sql.execute \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "IF NOT EXISTS (SELECT * FROM sys.tables WHERE name = '\''TestLog'\'') CREATE TABLE TestLog (Id INT IDENTITY, Message NVARCHAR(MAX), CreatedAt DATETIME DEFAULT GETDATE())"
  }' | jq
# Expected: rowsAffected: -1 (DDL command)

测试2：批量插入

# Insert multiple records
for i in {1..5}; do
  curl -X POST http://localhost:5000/tools/sql.execute \
    -H "Content-Type: application/json" \
    -d "{
      \"sql\": \"INSERT INTO TestLog (Message) VALUES (@Msg)\",
      \"parameters\": {
        \"@Msg\": \"Test message $i\"
      }
    }"
done

测试3：验证

curl -X POST http://localhost:5000/tools/sql.query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT COUNT(*) AS TotalRecords FROM TestLog"
  }' | jq
# Expected: TotalRecords: 5

整合

Claude桌面集成

启用Claude Desktop以使用此MCP服务器访问数据库和API。

步骤1：查找配置文件

# macOS
open ~/Library/Application\ Support/Claude/

# Windows
explorer %APPDATA%\Claude\

# Linux
cd ~/.config/Claude/

步骤2：编辑配置

打开或创建 claude_desktop_config.json:

{
  "mcpServers": {
    "sql-api-server": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/mcp.NET/src/Mcp.SqlApiServer"
      ],
      "env": {
        "Sql__ConnectionString": "Server=localhost;Database=MyDb;User Id=sa;Password=YourPassword;Encrypt=False;TrustServerCertificate=True"
      }
    }
  }
}

步骤3：重新启动克劳德桌面

步骤4：测试集成

在克劳德桌面聊天中：

Can you query the SQL Server to show me the current date and time?

克劳德应执行：

SELECT GETDATE() AS CurrentDateTime

迷你AGI后端集成

与您的AI代理编排系统集成。

请参阅中的完整集成指南 README-迷你AGI集成部分或访问 mini-AGI_后端存储库.

快速摘要：

构建MCP服务器： dotnet publish -c Release -o ./publish
创建Python桥适配器（在README中提供）
在迷你AGI工具注册表中注册工具
配置环境变量
启动迷你AGI后端

IIS部署

将MCP服务器部署到Windows server上的Internet Information Services（IIS），以用于企业托管。

为什么选择IIS？

具有负载平衡的企业级托管
Windows身份验证集成
通过IIS管理器进行集中管理
自动重启和健康监测
SSL/HTTPS终止

先决条件：

Windows Server 2016+（或Windows 10/11 Pro）
IIS 10.0+与ASP。NET核心模块
.NET 8运行时（托管捆绑包）

快速入门：

# 1. Publish application
dotnet publish src/Mcp.SqlApiServer -c Release -o C:\Publish\McpServer

# 2. Copy to IIS directory
Copy-Item C:\Publish\McpServer C:\inetpub\wwwroot\McpServer -Recurse

# 3. Create application pool and website
Import-Module WebAdministration
New-WebAppPool -Name "McpServerPool"
New-Website -Name "McpServer" -ApplicationPool "McpServerPool" -PhysicalPath "C:\inetpub\wwwroot\McpServer" -Port 5000

# 4. Configure environment
[Environment]::SetEnvironmentVariable("MCP_TRANSPORT_MODE", "http", "Machine")
[Environment]::SetEnvironmentVariable("Sql__ConnectionString", "Server=localhost;...", "Machine")

# 5. Start website
Start-Website -Name "McpServer"

# 6. Test
Invoke-WebRequest http://localhost:5000/health

完整指南：

有关详细的分步IIS部署说明，请参阅 IIS_DEPLOYMENT.md 其中包括：

✅ 先决条件和Windows功能安装
✅ 发布和传输应用程序文件
✅ 应用程序池配置和优化
✅ 网站创建和绑定设置
✅ 环境变量和安全配置
✅ SSL/HTTPS证书安装
✅ 防火墙和SQL Server访问设置
✅ 性能调优和缓存
✅ 监控和记录设置
✅ 全面的故障排除指南

部署后访问URL：

健康检查： http://your-server:5000/health
工具列表： http://your-server:5000/tools
MCP端点： http://your-server:5000/mcp

配置

SQL Server选项

编辑 appsettings.json:

{
  "Sql": {
    "ConnectionString": "Server=localhost;Database=MyDb;...",
    "BlockDdlOperations": true,
    "MaxRowsReturned": 10000,
    "QueryTimeoutSeconds": 30
  }
}

设置	说明	默认	推荐
`ConnectionString`	SQL Server连接字符串	（必需）	使用用户机密
`BlockDdlOperations`	阻止DROP、TRUNCATE、ALTER	`true`	`true` （生产）
`MaxRowsReturned`	限制行数（0=无限制）	`10000`	`1000-10000`
`QueryTimeoutSeconds`	查询执行超时	`30`	`30-60`

HTTP工具选项

{
  "HttpTool": {
    "AllowedHosts": ["api.github.com", "httpbin.org"],
    "DefaultTimeoutSeconds": 30,
    "MaxTimeoutSeconds": 120,
    "AllowAllHosts": false
  }
}

设置	说明	默认	推荐
`AllowedHosts`	允许的主机名	`[]`	列出特定域
`DefaultTimeoutSeconds`	默认请求超时	`30`	`15-30`
`MaxTimeoutSeconds`	允许的最大超时时间	`120`	`60-120`
`AllowAllHosts`	禁用主机筛选	`false`	`false` （总是）

API 参考

工具：http.call

目的： 执行对外部API的HTTP请求

输入架构：

{
  method: string;          // HTTP method (GET, POST, etc.)
  url: string;             // Full URL
  headers?: object;        // Optional headers
  query?: object;          // Optional query parameters
  body?: object;           // Optional JSON body
  timeoutSeconds?: number; // Optional timeout override
}

输出架构：

{
  statusCode: number;           // HTTP status code
  headers: Record<string, string>; // Response headers
  bodyText: string;             // Response body as text
}

例子：

{
  "method": "GET",
  "url": "https://api.github.com/users/octocat",
  "headers": {
    "Authorization": "Bearer ghp_xxxxxxxxxxxx"
  },
  "query": {
    "per_page": 10
  }
}

工具：sql.query

目的： 在SQL Server上执行SELECT查询

输入架构：

{
  sql: string;                         // SELECT statement
  parameters?: Record<string, any>;    // Named parameters
}

输出架构：

{
  rows: Array<Record<string, any>>;  // Query results
  rowCount: number;                   // Number of rows
}

例子：

{
  "sql": "SELECT * FROM Users WHERE Status = @Status AND CreatedDate > @Date",
  "parameters": {
    "@Status": "active",
    "@Date": "2024-01-01"
  }
}

工具：sql.execute

目的： 在SQL Server上执行INSERT、UPDATE、DELETE

输入架构：

{
  sql: string;                         // DML statement
  parameters?: Record<string, any>;    // Named parameters
}

输出架构：

{
  rowsAffected: number;  // Number of rows modified
}

例子：

{
  "sql": "UPDATE Users SET LastLogin = GETDATE() WHERE Id = @UserId",
  "parameters": {
    "@UserId": 123
  }
}

安全

安全最佳实践

1.连接字符串

✅ 做：使用用户机密或环境变量
❌ do not 的常用口语形式：将连接字符串提交到源代码管理
✅ 做：在生产中使用加密连接(Encrypt=True)
❌ do not 的常用口语形式：使用 TrustServerCertificate=True 生产中

2.HTTP允许列表

✅ 做：严格限制允许的东道主
❌ do not 的常用口语形式：启用 AllowAllHosts 生产中
✅ 做：使用特定域名（非通配符）
❌ do not 的常用口语形式：允许访问内部网络

3.SQL操作

✅ 做：保持 BlockDdlOperations 启用
❌ do not 的常用口语形式：允许在生产环境中使用DDL
✅ 做：始终使用参数化查询
❌ do not 的常用口语形式：使用字符串连接构建SQL

4.网络安全

✅ 做：在生产中使用stdio传输
❌ do not 的常用口语形式：将HTTP模式暴露给公共互联网
✅ 做：对所有外部API调用使用HTTPS
❌ do not 的常用口语形式：接受未经验证的自签名证书

安全检查列表

在部署到生产环境之前：

[]连接字符串使用加密连接
[]存储在安全秘密管理中的连接字符串
[ ] BlockDdlOperations 是 true
[ ] AllowAllHosts 是 false
[]已添加特定主机 AllowedHosts
[]查询超时已适当配置
[]已配置最大行数限制
[]审查日志以确定是否存在敏感数据泄露
[]HTTP模式已禁用（仅限stdio）
[]服务器以最低权限帐户运行

故障排除

常见问题

问题1：“未配置SQL连接字符串”

症状：

ERROR: SQL connection string is not configured.
Please set Sql:ConnectionString in appsettings.json or user secrets.

解决：

设置用户机密：

cd src/Mcp.SqlApiServer
dotnet user-secrets set "Sql:ConnectionString" "Server=..."

设置环境变量：

export Sql__ConnectionString="Server=..."

检查应用程序设置：

cat src/Mcp.SqlApiServer/appsettings.Development.json | grep ConnectionString

问题2：“主机'example.com'不在允许的主机列表中”

症状：

{
  "error": "Host 'example.com' is not in the allowed hosts list. Allowed hosts: api.github.com, httpbin.org"
}

解决：

将主机添加到配置中：

{
  "HttpTool": {
    "AllowedHosts": [
      "api.github.com",
      "httpbin.org",
      "example.com"  ← Add this
    ]
  }
}

仅用于测试：

{
  "HttpTool": {
    "AllowAllHosts": true  ⚠️ Development only!
  }
}

问题3：“不允许DDL操作”

症状：

{
  "error": "DDL operations (DROP, TRUNCATE, ALTER, CREATE, etc.) are not allowed."
}

说明： 这是一个安全功能，用于防止意外的架构更改。

解决：

开发/测试：

{
  "Sql": {
    "BlockDdlOperations": false  ⚠️ Use carefully
  }
}

使用数据库管理工具 改为DDL操作

问题4：连接超时

症状：

System.Data.SqlClient.SqlException: Timeout expired

解决：

增加查询超时时间：

{
  "Sql": {
    "QueryTimeoutSeconds": 60
  }
}

检查SQL Server性能：

-- Check long-running queries
SELECT * FROM sys.dm_exec_requests WHERE status = 'running'

优化查询：
- 添加适当的索引
- 减少返回的数据
- 有效地使用WHERE子句

问题5:HTTP模式未启动

症状：

Failed to bind to address http://0.0.0.0:5000

解决：

端口已在使用中：

# Find process using port 5000
lsof -i :5000  # macOS/Linux
netstat -ano | findstr :5000  # Windows

# Use different port
export MCP_HTTP_PORT=8080
dotnet run --project src/Mcp.SqlApiServer http

权限被拒绝：

# Use port > 1024
export MCP_HTTP_PORT=5000

问题6:MCP检查员无法连接

症状：

检查器显示“连接失败”
浏览器控制台中的“网络错误”

解决：

验证服务器是否正在运行：
```
curl http://localhost:5000/health
```
检查CORS：
- HTTP模式自动启用CORS
- 尝试使用localhost而不是127.0.0.1

检查防火墙：

# Temporarily disable firewall (testing only)
# Or add rule for port 5000

请改用stdio模式：

npx @modelcontextprotocol/inspector dotnet run --project src/Mcp.SqlApiServer

调试模式

启用详细日志记录：

# Set logging level to Debug
export Logging__LogLevel__Default=Debug
dotnet run --project src/Mcp.SqlApiServer http

查看详细日志：

# All logs go to stderr
dotnet run --project src/Mcp.SqlApiServer 2> debug.log

使用迷你AGI后端

[以前的小型AGI集成内容保留在此处-保留现有的详细集成指南]

贡献

我们欢迎捐款！请看 CLAUDE.md 发展指南。

开发设置：

git clone https://github.com/b9b4ymiN/mcp.NET.git
cd mcp.NET
dotnet restore
dotnet build
dotnet test

编码标准：

遵循C#命名约定
对I/O操作使用async/await
添加XML文档注释
为新功能编写单元测试
为API更改更新README

许可证

[您的许可证在这里]

资源

版本： 1.0.0 最后更新时间： 2024-01-15 维护人员： [你的名字]

有关问题和疑问，请访问 GitHub问题页面。

使用说明

MCP SQL/API服务器

📋 目录

概述

特性

🌐 HTTP API工具(http.call)

🗄️ SQL Server工具

🔧 双重运输模式

先决条件

入门指南

步骤1：克隆和构建

步骤2：配置SQL Server

选项A：使用用户机密（建议用于开发）

选项B：使用Docker SQL Server（最快）

选项C：使用环境变量

步骤3：配置HTTP安全

步骤4：运行服务器

在标准模式下运行（默认-生产）

在HTTP模式下运行（测试/开发）

测试指导

使用HTTP模式进行测试

测试1：服务器健康检查

测试2：列出可用工具

测试3:HTTP API工具

测试4:SQL查询工具

测试5:SQL执行工具

MCP检验员测试

方法1:HTTP连接（推荐）

方法2：标准连接

测试单个工具

HTTP调用工具测试套件

SQL查询工具测试套件

SQL执行工具测试套件

整合

Claude桌面集成

迷你AGI后端集成

IIS部署

配置

SQL Server选项

HTTP工具选项

API 参考

工具：http.call

工具：sql.query

工具：sql.execute

安全

安全最佳实践

1.连接字符串

2.HTTP允许列表

3.SQL操作

4.网络安全

安全检查列表

故障排除

常见问题

问题1：“未配置SQL连接字符串”

问题2：“主机'example.com'不在允许的主机列表中”

问题3：“不允许DDL操作”

问题4：连接超时

问题5:HTTP模式未启动

问题6:MCP检查员无法连接

调试模式

使用迷你AGI后端

贡献

许可证

资源

相关 MCP

HTTP API转MCP工具服务

可配置MCP服务器

MySQL查询服务器

DBHub 数据库MCP服务器

Qdrant向量搜索MCP服务器

知识图谱存储服务

🌐 HTTP API工具(`http.call`)