Name: 工具搜索网关
Author: pleaseai

使用说明

MCP网关

使用MCP服务器和CLI搜索MCP工具 正则表达式, BM25，或 语义（嵌入） 搜索。

Monorepo结构

mcp-gateway/
├── packages/
│   ├── core/                # Core search engine (@pleaseai/mcp-core)
│   └── mcp/                 # CLI + MCP server (@pleaseai/mcp-gateway)
├── turbo.json               # Turbo build configuration
└── package.json             # Root workspace configuration

特性

多种搜索模式:
- 正则表达式：工具名称和描述的模式匹配
- BM25：传统文本搜索排名算法
- 嵌入：使用向量相似度进行语义搜索
可配置的嵌入提供程序:
- 本地：minilm：通过transformers.js的全MiniLM-L6-v2（384 dims，无需API密钥）
- 本地：mdbr叶子：MongoDB MDBR Leaf IR（256调光，针对搜索进行了优化）
- api：openai：OpenAI嵌入API
- api：航行：Voyage AI嵌入
工具来源:
- 从JSON/YAML文件加载工具定义
- 从配置的MCP服务器自动发现工具
- 远程MCP服务器的OAuth 2.1身份验证支持
MCP服务器：完整的MCP协议实施，包括：
- search_tools -搜索索引工具
- get_tool -使用CLI使用模板获取详细的工具架构
- tool_search_info / list_tools -索引元数据
IDE集成：多个IDE的安装命令

安装

Claude代码插件

# Add the marketplace
/plugin marketplace add pleaseai/claude-code-plugins

# Install the plugin
/plugin install mcp-gateway@pleaseai

自制（macOS/Linux）

brew install pleaseai/tap/mcp-gateway

外壳脚本

curl -fsSL https://raw.githubusercontent.com/pleaseai/mcp-gateway/main/install.sh | bash

安全说明：管道 curl 到 bash 执行远程代码而不进行检查。为了增加安全性，您可以先下载并检查脚本：
curl -fsSL https://raw.githubusercontent.com/pleaseai/mcp-gateway/main/install.sh -o install.sh
# ... inspect install.sh ...
bash install.sh

npm/npx

# Using npx (no install required)
npx @pleaseai/mcp-gateway index <tool-sources>
npx @pleaseai/mcp-gateway search "query"
npx @pleaseai/mcp-gateway serve

# Global install
npm install -g @pleaseai/mcp-gateway

开发设置

bun install
bun run build

CLI使用情况

索引工具

从工具定义或MCP服务器构建搜索索引：

# Index from configured MCP servers (reads from .please/mcp.json)
npx @pleaseai/mcp-gateway index

# Index from specific JSON/YAML files
npx @pleaseai/mcp-gateway index tools.json

# Index without embeddings (faster, BM25/regex only)
npx @pleaseai/mcp-gateway index --no-embeddings

# Index with local embeddings (default: local:minilm)
npx @pleaseai/mcp-gateway index

# Index with specific provider
npx @pleaseai/mcp-gateway index -p local:mdbr-leaf
npx @pleaseai/mcp-gateway index -p api:openai

# Exclude specific MCP servers
npx @pleaseai/mcp-gateway index --exclude server1,server2

# Custom output path (default: .please/mcp/index.json)
npx @pleaseai/mcp-gateway index -o ./my-index.json

# Force overwrite existing index
npx @pleaseai/mcp-gateway index -f

搜索工具

在索引中搜索工具：

# BM25 search (default)
npx @pleaseai/mcp-gateway search "file operations"

# Regex search
npx @pleaseai/mcp-gateway search "read.*file" --mode regex

# Semantic search
npx @pleaseai/mcp-gateway search "tools for sending messages" --mode embedding

# Limit results
npx @pleaseai/mcp-gateway search "database" -k 5

# JSON output
npx @pleaseai/mcp-gateway search "database" --format json

启动MCP服务器

启动MCP服务器进行工具搜索：

# Default (stdio transport, reads from .please/mcp/index.json)
npx @pleaseai/mcp-gateway serve

# Or just (serve is the default command)
npx @pleaseai/mcp-gateway

# Specify index path
npx @pleaseai/mcp-gateway serve -i ./data/index.json

# Set default search mode
npx @pleaseai/mcp-gateway serve -m embedding

安装到IDE

将MCP服务器配置安装到IDE：

# Claude Code (default, creates .mcp.json)
npx @pleaseai/mcp-gateway install

# Claude Desktop
npx @pleaseai/mcp-gateway install --ide claude-desktop

# Cursor
npx @pleaseai/mcp-gateway install --ide cursor

# VS Code
npx @pleaseai/mcp-gateway install --ide vscode

# Gemini CLI
npx @pleaseai/mcp-gateway install --ide gemini

# OpenAI Codex
npx @pleaseai/mcp-gateway install --ide codex

# Preview without writing
npx @pleaseai/mcp-gateway install --dry-run

管理MCP服务器

管理MCP服务器配置（类似于 claude mcp 命令）：

# Add a stdio server (default scope: local)
npx @pleaseai/mcp-gateway mcp add my-server npx -- @some/mcp-server --option value

# Add an HTTP server
npx @pleaseai/mcp-gateway mcp add notion --transport http https://mcp.notion.com/mcp

# Add with environment variables
npx @pleaseai/mcp-gateway mcp add my-server npx @some/mcp -e API_KEY=xxx -e DEBUG=true

# Add to specific scope
npx @pleaseai/mcp-gateway mcp add my-server npx @some/mcp --scope project
npx @pleaseai/mcp-gateway mcp add my-server npx @some/mcp --scope user

# List all configured servers
npx @pleaseai/mcp-gateway mcp list
npx @pleaseai/mcp-gateway mcp ls --format json

# Get server details
npx @pleaseai/mcp-gateway mcp get my-server

# Remove a server
npx @pleaseai/mcp-gateway mcp remove my-server
npx @pleaseai/mcp-gateway mcp rm my-server --scope project

配置范围：

范围	路径	目的
`local` （默认）	`.please/mcp.local.json`	本地覆盖，gitignored
`project`	`.please/mcp.json`	项目范围内，致力于git
`user`	`~/.please/mcp.json`	用户范围设置

范围详细信息：

local：不应共享的个人配置。自动添加到 .please/.gitignore。用于API密钥、本地路径或实验服务器。
project：团队的共享配置。承诺使用git，以便所有团队成员使用相同的MCP服务器。
user：所有项目的全局配置。适用于您希望随处可用的个人MCP服务器。

范围解决顺序：

当多个作用域定义同一服务器时，它们将以以下优先级（最高优先）合并：

local -本地覆盖优先
project -项目设置覆盖用户设置
user -基础配置

这允许您在中定义团队范围内的服务器 project 范围，同时覆盖中的特定设置（如API键） local 范围。

发展

# Install dependencies
bun install

# Build all packages
bun run build

# Build specific package
bun run build --filter=@pleaseai/mcp-core

# Development mode (watch)
bun run dev

# Run tests
bun run test

# Type check
bun run typecheck

# Clean build artifacts
bun run clean

包裹

@pleaseai/mcp核心

核心搜索引擎：

搜索策略（正则表达式、BM25、嵌入）
嵌入提供商（本地MiniLM、本地MDBR Leaf、OpenAI、Voyage AI）
索引管理（加载器、构建器、存储）

@pleaseai/mcp网关

CLI+MCP服务器暴露：

index -从工具定义或MCP服务器构建搜索索引
search -搜索工具
serve -启动MCP服务器（默认命令）
install -安装到IDE配置
mcp -管理MCP服务器配置

MCP工具：

search_tools -使用查询、模式、top_k、阈值进行搜索
get_tool -获取详细的工具模式、元数据和CLI使用模板
tool_search_info -获取索引元数据
list_tools -列出所有带分页的索引工具

MCP服务器工具

`search_tools`

使用正则表达式、BM25或语义搜索搜索工具。返回按相关性排序的匹配工具。

参数：

query （string，必填）：搜索查询字符串
mode （字符串，可选）：搜索模式- regex, bm25，或 embedding （默认值： bm25)
top_k （数字，可选）：返回的最大结果数（默认值：10）
threshold （数字，可选）：最低分数阈值0-1（默认值：0）

`get_tool`

获取特定工具的详细信息，包括其输入模式和CLI使用模板。

参数：

name （字符串，必填）：搜索结果中的工具名称

答复：

name：完整工具名称（格式： server__toolName)
description：这个工具做什么
requiredFields：所需参数名称数组
parameters：包含名称、类型、必需标志和描述的所有参数的数组
inputSchema：完成JSON模式以进行验证
cliUsage：用于通过Bash工具执行的CLI命令模板

推荐工作流程： search_tools → get_tool → (use cliUsage 通过Bash工具）

为什么选择CLI而不是MCP call_tool?

通过Bash工具使用CLI可以使主机应用程序（例如Claude Code）进行适当的权限检查。当通过CLI执行工具时，主机可以在运行之前验证用户的同意敏感操作。直接MCP call_tool 绕过这些权限检查，这可能是不可取的在工具执行需要用户批准的环境中。

`tool_search_info`

获取有关工具搜索索引的信息。

`list_tools`

按页码列出索引中的所有工具。

参数：

limit （数字，可选）：返回的最大工具数（默认值：100）
offset （数字，可选）：分页偏移量（默认值：0）

通过CLI调用工具

使用提供的CLI命令执行发现的工具 get_tool:

# Basic usage (command template from get_tool response)
mcp-gateway call <server>__<tool> --param1 "value1" --param2 "value2"

# Example: Call a file read tool
mcp-gateway call filesystem__read_file --path "/tmp/example.txt"

# With JSON arguments for complex parameters
mcp-gateway call myserver__create_item --data '{"name": "test", "count": 5}'

这 cliUsage 字段在 get_tool response提供了一个即用型命令模板。

OAuth身份验证

MCP网关支持需要OAuth 2.1身份验证的远程MCP服务器。

运作原理

在OAuth保护的服务器上索引或调用工具时，CLI将自动检测身份验证要求
浏览器窗口打开，供您完成OAuth流程
令牌安全地存储在 ~/.please/oauth/ 供将来使用
令牌刷新是自动处理的

支持的流量

PKCE授权码（推荐）
长期会话的令牌刷新

令牌存储

OAuth令牌按服务器存储在 ~/.please/oauth/<server-name>.json。这些文件是自动管理的，不应手动编辑。

配置

默认路径

索引文件: .please/mcp/index.json
搜索模式: bm25
嵌入提供者: local:minilm

环境变量

# OpenAI API Key (for api:openai embedding provider)
OPENAI_API_KEY=sk-...

# Voyage AI API Key (for api:voyage embedding provider)
VOYAGE_API_KEY=pa-...

IDE配置位置

IDE	配置路径
克劳德代码	`.mcp.json` （项目根）
克劳德桌面	`~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）
光标	`.cursor/mcp.json`
VS代码	`.vscode/mcp.json`
Gemini CLI	`~/.gemini/settings.json`
OpenAI Codex	`~/.codex/config.toml`

工具定义格式

工具定义遵循MCP工具规范：

{
  "tools": [
    {
      "name": "read_file",
      "title": "Read File",
      "description": "Read the contents of a file from the filesystem",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "The path to the file to read"
          }
        },
        "required": ["path"]
      }
    }
  ]
}

文档

搜索架构 -搜索引擎的工作原理（策略、索引、无向量数据库）
嵌入模型比较 -本地嵌入模型的基准结果和建议

参考文献

许可证

麻省理工学院

使用说明

MCP网关

Monorepo结构

特性

安装

Claude代码插件

自制（macOS/Linux）

外壳脚本

npm/npx

开发设置

CLI使用情况

索引工具

搜索工具

启动MCP服务器

安装到IDE

管理MCP服务器

发展

包裹

@pleaseai/mcp核心

@pleaseai/mcp网关

MCP服务器工具

search_tools

get_tool

tool_search_info

list_tools

通过CLI调用工具

OAuth身份验证

运作原理

支持的流量

令牌存储

配置

默认路径

环境变量

IDE配置位置

工具定义格式

文档

参考文献

许可证

相关 MCP

Figma MCP服务器

Markdown转换服务

AI持久记忆服务器

MCP 协议测试服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

`search_tools`

`get_tool`

`tool_search_info`

`list_tools`