MCP 服务器

此仓库包含两个 MCP (模型上下文协议) 服务器：

1. 文件查找器 MCP - 用于搜索文件
2. Whisper STT MCP - 用于将语音转换为文本

文件查找器 MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，提供文件搜索功能。它允许搜索文件名中包含指定文本片段的文件。

前提条件

• Node.js (版本 14 或更高)
• npm (版本 6 或更高)
• Python 3.6 或更高版本 (用于 HTTP 服务器)

安装

1. 克隆或下载此仓库
2. 进入项目目录
3. 安装依赖项：

   npm install
   

4. 构建项目：

   npm run build
   

启动服务器

项目提供了几种启动 MCP 服务器的选项：

选项 1：直接启动 MCP 服务器

您可以使用 Node.js 直接启动 MCP 服务器：

npm start

或

node build/index.js

这将启动服务器，它将等待 stdin/stdout 上的 JSON-RPC 请求。

选项 2：启动 HTTP 服务器和 MCP 代理

此选项使用 Python HTTP 服务器和 MCP 代理，该代理将请求重定向到 HTTP 服务器：

1. 首先启动 HTTP 服务器：

   npm run start:python
   

   或

   python main.py
   

2. 然后在另一个终端中启动 MCP 代理：

   npm run start:http
   

   或

   node build/index-http.js
   

选项 3：与 VS Code 集成 (Cline 扩展)

要将服务器与 VS Code 和 Cline 扩展集成：

1. 找到 MCP 配置文件：

   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. 将以下配置添加到配置文件中的 mcpServers 对象：

"file-finder-mcp": {
  "command": "node",
  "args": ["<项目完整路径>/build/index.js"],
  "disabled": false,
  "autoApprove": []
}

要使用 HTTP 代理：

"file-finder-mcp-http": {
  "command": "node",
  "args": ["<项目完整路径>/build/index-http.js"],
  "disabled": false,
  "autoApprove": []
}

将 <项目完整路径> 替换为您的项目目录的实际路径。

3. 重新启动 VS Code 以加载更新的设置。

可用工具

MCP 服务器提供一个工具：

• search_files: 搜索文件名中包含指定片段的文件
  • 参数：
    • fragment (字符串，必需): 用于在文件名中搜索的文本片段

使用示例

<use_mcp_tool>
<server_name>file-finder-mcp</server_name>
<tool_name>search_files</tool_name>
<arguments>
{
  "fragment": ".py"
}
</arguments>
</use_mcp_tool>

此示例搜索所有文件名中包含 ".py" 的文件。

HTTP 服务器 (main.py)

项目根目录中有一个 main.py 文件，它实现了用于搜索文件的 HTTP 服务器。此服务器提供 REST API 来搜索文件名中包含指定片段的文件。

启动 HTTP 服务器

1. 进入项目根目录
2. 使用 Python 启动服务器：

   python main.py
   

3. 服务器将在 http://localhost:8080 上启动

使用 API

要搜索文件，请向 /search 发送带有查询参数 q 的 GET 请求：

http://localhost:8080/search?q=.json

此请求将返回一个 JSON 数组，其中包含有关所有文件名中包含 ".json" 的文件的信息。数组中的每个元素包含以下字段：

• name: 文件名
• path: 文件的绝对路径
• size: 文件大小（以字节为单位）
• created: 文件的创建日期和时间

示例响应：

[
    {
        "name": "package.json",
        "path": "/absolute/path/to/package.json",
        "size": 1234,
        "created": "Wed Feb 26 17:00:00 2025"
    }
]

Whisper STT MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，它使用 faster-whisper 库提供语音到文本的转换功能。它允许将音频数据转录为文本，并自动检测语言。

前提条件

• Node.js (版本 14 或更高)
• npm (版本 6 或更高)
• Python 3.6 或更高版本
• faster-whisper (使用 pip install faster-whisper 安装)

安装

1. 克隆或下载此仓库
2. 进入项目目录
3. 安装依赖项：

   npm install
   pip install faster-whisper
   

4. 构建项目：

   npm run build
   

启动服务器

项目提供了几种启动 Whisper MCP 服务器的选项：

选项 1：直接启动 MCP 服务器

您可以使用 Node.js 直接启动 MCP 服务器：

npm run start:whisper

或

node build/whisper-index.js

这将启动服务器，它将等待 stdin/stdout 上的 JSON-RPC 请求。

选项 2：启动 HTTP 服务器和 MCP 代理

此选项使用 Python HTTP 服务器和 MCP 代理，该代理将请求重定向到 HTTP 服务器：

1. 首先启动 HTTP 服务器：

   npm run start:whisper:python
   

   或

   python whisper_server.py
   

2. 然后在另一个终端中启动 MCP 代理：

   npm run start:whisper:http
   

   或

   node build/whisper-index-http.js
   

选项 3：与 VS Code 集成 (Cline 扩展)

要将服务器与 VS Code 和 Cline 扩展集成：

1. 找到 MCP 配置文件：

   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings\cline_mcp_settings.json
   • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. 将以下配置添加到配置文件中的 mcpServers 对象：

"whisper-stt-mcp": {
  "command": "node",
  "args": ["<项目完整路径>/build/whisper-index.js"],
  "disabled": false,
  "autoApprove": []
}

要使用 HTTP 代理：

"whisper-stt-mcp-http": {
  "command": "node",
  "args": ["<项目完整路径>/build/whisper-index-http.js"],
  "disabled": false,
  "autoApprove": []
}

将 <项目完整路径> 替换为您的项目目录的实际路径。

3. 重新启动 VS Code 以加载更新的设置。

可用工具

MCP 服务器提供一个工具：

• transcribe_audio: 使用 faster-whisper 将音频数据转换为文本
  • 参数：
    • audio_base64 (字符串，必需): base64 格式的音频数据
    • language (字符串，可选): 语言代码 (例如, "en", "ru")。如果未指定，将自动检测语言。

使用示例

<use_mcp_tool>
<server_name>whisper-stt-mcp</server_name>
<tool_name>transcribe_audio</tool_name>
<arguments>
{
  "audio_base64": "BASE64_ENCODED_AUDIO_DATA",
  "language": "ru"
}
</arguments>
</use_mcp_tool>

此示例将音频数据转换为文本，假设音频为俄语。

HTTP 服务器 (whisper_server.py)

项目根目录中有一个 whisper_server.py 文件，它实现了用于将语音转换为文本的 HTTP 服务器。此服务器提供 REST API 来转录音频数据为文本。

启动 HTTP 服务器

1. 进入项目根目录
2. 使用 Python 启动服务器：

   python whisper_server.py
   

3. 服务器将在 http://localhost:8081 上启动

使用 API

要转录音频，请向 /transcribe 发送带有 JSON 主体的 POST 请求，其中包含：

• audio: base64 格式的音频数据字符串
• language (可选): 语言代码 (例如, "en", "ru")

示例请求：

{
  "audio": "BASE64_ENCODED_AUDIO_DATA",
  "language": "ru"
}

响应将包含：

• text: 完整的转录文本
• segments: 带有时间戳的片段数组
• language: 检测到的语言
• language_probability: 语言检测的概率

示例响应：

{
  "text": "这是一个转录文本的示例。",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "这是一个示例"
    },
    {
      "start": 2.5,
      "end": 4.0,
      "text": "转录文本的示例。"
    }
  ],
  "language": "ru",
  "language_probability": 0.98
}

故障排除

• 如果您收到 "No connection found for server" 错误，请确保在更新 MCP 设置后重新启动 VS Code。
• 如果服务器没有响应，请检查 MCP 设置中的路径是否正确，并指向已构建的 JavaScript 文件。
• 确保服务器已正确构建，在尝试使用它之前执行 npm run build。
• 要使用 HTTP 代理，请确保相应的 HTTP 服务器已启动 (file-finder 的端口为 8080，whisper-stt 的端口为 8081)。
• 如果 faster-whisper 出现问题，请确保已正确安装该库，并且您具有使用 GPU 所需的依赖项（如果您使用 GPU）。

项目结构

以下是项目主要文件及其用途的列表：

根目录

• src/index.ts - 用于文件搜索的 TypeScript MCP 服务器的源代码（直接实现）
• src/index-http.ts - 用于文件搜索的 HTTP 服务器的 TypeScript MCP 代理的源代码
• src/whisper-index.ts - 用于语音到文本转换的 TypeScript MCP 服务器的源代码（直接实现）
• src/whisper-index-http.ts - 用于语音到文本转换的 HTTP 服务器的 TypeScript MCP 代理的源代码
• build/index.js - 用于文件搜索的 MCP 服务器的已编译 JavaScript 代码
• build/index-http.js - 用于文件搜索的 MCP 代理的已编译 JavaScript 代码
• build/whisper-index.js - 用于语音到文本转换的 MCP 服务器的已编译 JavaScript 代码
• build/whisper-index-http.js - 用于语音到文本转换的 MCP 代理的已编译 JavaScript 代码
• tsconfig.json - TypeScript 配置
• package.json - 包描述和依赖项
• main.py - 用于文件搜索的 Python HTTP 服务器
• whisper_server.py - 用于语音到文本转换的 Python HTTP 服务器
• README.md - 项目文档（此文件）