使用说明

用于Cursor IDE的MCP服务器

此项目托管多个模型上下文协议（MCP）服务器，这些服务器旨在与Cursor IDE一起工作。MCP服务器允许Cursor通过标准化的通信协议利用外部工具和功能。

先决条件

Node.js（v16或更新版本）
npm或纱线

如何使用

克隆此存储库：

git clone https://github.com/yourusername/mcp-servers.git
cd mcp-servers

安装依赖项并设置所有内容：
```
npm run setup
```
此命令将：
- 安装所有依赖项
- 构建TypeScript项目
- 为Cursor IDE集成生成必要的脚本
- 提供在Cursor中设置每个服务器的说明
配置游标IDE：
- 打开光标IDE
- 转到光标设置>功能>Mcp服务器
- 点击“添加新Mcp服务器”
- 输入服务器的名称（例如“postgres”）
- 对于“连接类型”，选择“命令”
- 对于“command”，粘贴prepare脚本提供的路径
- 点击“保存”
环境变量：
- 复制 .env.example 文件到 .env
- 使用您自己的凭据为每个服务更新变量
在游标IDE中使用Mcp：
- 打开编辑器
- 确保你使用的是代理模式（建议使用克劳德3.7十四行诗思维）
- 提交您想要定位的消息

什么是MCP？

模型上下文协议（MCP）是一种开放协议，它规范了应用程序如何向LLM（大型语言模型）提供上下文。将MCP视为Cursor IDE和外部工具之间的通信接口。MCP服务器公开了Cursor IDE可以用来增强其功能的工具。

项目结构

mcp-servers/
├── src/
│   ├── servers/                  # Individual MCP servers
│   │   ├── postgres-server/      # PostgreSQL integration server
│   │   │   └── postgres-server.ts
│   │   ├── kubernetes-server/    # Kubernetes integration server
│   │   │   └── kubernetes-server.ts
│   │   ├── lease-pdf-server/     # PDF processing server
│   │   │   └── pdf-server.ts
│   │   └── ... (more servers)
│   ├── template/                 # Reusable templates
│   │   └── mcp-server-template.ts
│   ├── index.ts                  # Server runner utility
│   └── run-all.ts                # Script to run all servers
├── package.json
└── tsconfig.json

可用服务器

目前，以下MCP服务器可用：

PostgreSQL服务器 -提供对PostgreSQL数据库的访问，以执行查询和检索模式信息
Kubernetes服务器 -提供对Kubernetes集群的访问，用于管理Pod、执行命令和检索日志
转档器 -提供PDF文档处理功能，包括文本提取、表单字段读/写和PDF生成

服务器配置

所有服务器都是通过环境变量配置的。创建一个 .env 项目根目录中的文件（或从中复制 .env.example)并配置您计划使用的服务：

# PostgreSQL Configuration (for PostgreSQL server)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=your_database_name
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
# POSTGRES_SSL_MODE=require # Uncomment if SSL is required
# POSTGRES_MAX_CONNECTIONS=10 # Optional: limit connection pool size

# Kubernetes Configuration (for Kubernetes server)
KUBECONFIG=/path/to/your/kubeconfig
# Alternative Kubernetes configuration:
# KUBE_API_URL=https://your-kubernetes-api-server
# KUBE_API_TOKEN=your-kubernetes-service-account-token

# PDF Server requires no additional configuration

可用工具

PostgreSQL服务器工具

mcp__get_database_info -检索有关连接的数据库的信息
mcp__list_tables -列出当前数据库架构中的所有表
mcp__get_table_structure -获取特定表的列定义
mcp__execute_query -对数据库执行自定义SQL查询

Kubernetes服务器工具

get_pods -使用可选的字段和标签选择器从指定的命名空间检索Pod
find_pods -在指定的命名空间中查找与名称模式匹配的Pod
kill_pod -删除指定命名空间中的pod
exec_in_pod -在指定的pod和容器中执行命令
get_pod_logs -从指定的pod中检索日志，包括容器、行数和上一个实例的选项

PDF服务器工具

read_pdf -从PDF文档中提取文本内容和表单字段数据
- 参数： input （string）-PDF文件路径或base64编码的PDF内容
- 退货： 带有成功状态、页数、提取文本、表单字段和元数据的JSON
write_pdf -创建新的PDF或使用内容和表单字段更新修改现有的PDF
- 参数：
  - content （对象）-要写的内容（文本和/或表单字段）
  - templatePdf （可选字符串）-模板PDF文件路径或base64内容
  - outputPath （可选字符串）-输出文件路径（如果未提供，则返回base64）
- 退货： 带有成功状态、输出路径和base64数据的JSON（如果适用）

运行服务器

快速开始

setup命令为每个服务器创建单独的shell脚本，这些脚本可以直接与Cursor IDE一起使用。运行后 npm run setup，您将看到每种服务器配置的说明。

使用辅助脚本运行服务器

要使用附带的辅助脚本运行特定服务器，请执行以下操作：

npm run server -- [server-name]

例如，要运行postgres服务器：

npm run server -- postgres

或者运行PDF服务器：

npm run server -- pdf

这将自动构建TypeScript代码并启动服务器。

手动运行单个服务器

要手动运行特定服务器，请执行以下操作：

npm run dev -- [server-name]

例如，要运行postgres服务器：

npm run dev -- postgres

或者运行PDF服务器：

npm run dev -- pdf

运行所有服务器

要同时运行所有服务器，请执行以下操作：

npm run dev:all

列出可用服务器

要查看所有可用服务器的列表：

npm run dev -- --list

测试您的MCP服务器

在连接到Cursor IDE之前，您可以测试MCP服务器的功能：

构建你的TypeScript项目：
```
npm run build
```
运行服务器：
```
npm run start:postgres
```
或者对于PDF服务器：
```
npm run start:pdf
```

为方便起见，此项目包括一个现成的Cursor脚本：

/path/to/mcp-servers/cursor-mcp-server.sh [server-name]

您可以在Cursor IDE配置中直接使用此脚本路径。如果没有提供服务器名称，则默认为postgres服务器。示例：

# Run postgres server (default)
/path/to/mcp-servers/cursor-mcp-server.sh

# Run PDF server
/path/to/mcp-servers/cursor-mcp-server.sh pdf

# Run kubernetes server
/path/to/mcp-servers/cursor-mcp-server.sh kubernetes

添加新的MCP服务器

要将新的MCP服务器添加到此项目中，请执行以下操作：

在下面为您的服务器创建一个新目录 src/servers/:
```
mkdir -p src/servers/my-new-server
```

创建服务器实现：

// src/servers/my-new-server/my-new-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Create an MCP server
const server = new McpServer({
  name: "My New Server",
  version: "1.0.0",
});

// Add your tools
server.tool(
  "my-tool",
  {
    param1: z.string().describe("Parameter description"),
    param2: z.number().describe("Parameter description"),
  },
  async ({ param1, param2 }) => {
    // Tool implementation
    return {
      content: [{ type: "text", text: `Result: ${param1} ${param2}` }],
    };
  }
);

// Start the server
async function startServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.log("My New Server started and ready to process requests");
}

// Start the server if this file is run directly
if (process.argv[1] === new URL(import.meta.url).pathname) {
  startServer();
}

export default server;

将您的服务器添加到中的服务器列表 src/index.ts 和 src/run-all.ts:

const servers = [
  // ... existing servers
  {
    name: "my-new-server",
    displayName: "My New Server",
    path: join(__dirname, "servers/my-new-server/my-new-server.ts"),
  },
];

更新package.json脚本（可选）：

"scripts": {
  // ... existing scripts
  "dev:my-new-server": "ts-node --esm src/servers/my-new-server/my-new-server.ts"
}

了解MCP服务器开发

在开发MCP服务器时，请记住：

工具是公开功能的主要方式。每个工具都应该：
- 有一个唯一的名字
- 使用Zod定义参数进行验证
- 以标准格式返回结果
沟通通过stdio进行游标集成。
响应格式 至关重要的是，MCP服务器必须遵循以下确切格式：
- 工具应返回以下内容 type: "text" 用于文本响应
- 避免使用不受支持的类型，如 type: "json" 直接
- 对于结构化数据，转换为JSON字符串并使用 type: "text"
- 例子：
```
return {
  content: [
    { type: "text", text: "Human-readable response" },
    { type: "text", text: JSON.stringify(structuredData, null, 2) },
  ],
};
```

建设项目

要构建项目，请运行：

npm run build