麦普顾问

Name: 麦普顾问
Author: istarwyh

作者：istarwyh70 星标更新：2025-11-09

安装使用来源：spider==github.com

项目介绍

技术文档摘要

MCP Advisor

English | 简体中文

简介

MCP Advisor 是一个发现和推荐服务，帮助AI助手通过自然语言查询探索模型上下文协议（MCP）服务器。它使用户更容易找到并利用适合特定任务的MCP工具。

用户故事

发现与推荐MCP服务器
- 作为AI代理开发者，我希望能够快速找到适用于特定任务的正确MCP服务器，使用自然语言查询。
- 示例提示："查找用于保险风险分析的MCP服务器"
安装与配置MCP服务器
- 作为一个普通用户，在发现了一个有用的MCP服务器后，我希望能够尽快安装并开始使用它。
- 示例提示："安装这个MCP: https://github.com/Deepractice/PromptX"

演示

https://github.com/user-attachments/assets/7a536315-e316-4978-8e5a-e8f417169eb1

使用方法

一旦配置完成，Nacos提供程序将在搜索MCP服务器时自动启用和使用。您可以使用自然语言进行查询，例如：

查找用于保险风险分析的MCP服务器

或者更具体地：

查找具有自然语言处理能力的MCP服务器

文档导航

快速入门指南 - 安装、配置和基本使用
技术参考 - 高级功能和搜索提供程序
贡献指南 - 开发设置和贡献指南
架构文档 - 系统架构细节
故障排除 - 常见问题及解决方案
路线图 - 未来开发计划

快速开始

安装

最快的方式是通过MCP配置集成MCP Advisor：

{
  "mcpServers": {
    "mcpadvisor": {
      "command": "npx",
      "args": ["-y", "@xiaohui-wang/mcpadvisor"]
    }
  }
}

将此配置添加到您的AI助手的MCP设置文件中：

MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json

通过 Smithery 安装

要通过 Smithery 自动安装Advisor for Claude Desktop：

npx -y @smithery/cli install @istarwyh/mcpadvisor --client claude

有关更多安装方法和详细配置，请参阅快速入门指南。

可选：本地 Meilisearch（提高推荐质量）

为了提升推荐质量，可以运行一个本地的 Meilisearch 实例：

pnpm meilisearch:start

这会在 http://localhost:7700 启动 Meilisearch，并从本地数据引导 mcp_servers 索引，同时将环境变量持久化到 ~/.meilisearch/env。在当前shell中加载它们：

source ~/.meilisearch/env

或者在启动 MCPAdvisor 时通过单个标志自动启用（无需手动设置环境变量）：

{
  "mcpServers": {
    "mcpadvisor": {
      "command": "npx",
      "args": ["-y", "@xiaohui-wang/mcpadvisor", "--local-meilisearch"]
    }
  }
}

开发者指南

架构概述

MCP Advisor 采用模块化架构，清晰地分离关注点并遵循函数式编程原则。代码库最近进行了重构（2025年），以提高可维护性和可扩展性：

graph TD
    Client["客户端应用程序"] --> |"MCP 协议"| Transport["传输层"]
    
    subgraph "MCP Advisor 服务器"
        Transport --> |"请求"| SearchService["搜索服务"]
        SearchService --> |"查询"| Providers["搜索提供程序"]
        
        subgraph "搜索提供程序"
            Providers --> MeilisearchProvider["Meilisearch 提供程序"]
            Providers --> GetMcpProvider["GetMCP 提供程序"]
            Providers --> CompassProvider["Compass 提供程序"]
            Providers --> NacosProvider["Nacos 提供程序"]
            Providers --> OfflineProvider["离线提供程序"]
        end
        
        OfflineProvider --> |"混合搜索"| HybridSearch["混合搜索引擎"]
        HybridSearch --> TextMatching["文本匹配"]
        HybridSearch --> VectorSearch["向量搜索"]
        
        SearchService --> |"合并与过滤"| ResultProcessor["结果处理器"]
        
        SearchService --> Logger["日志系统"]
    end

项目结构

代码库遵循干净架构原则，具有组织良好的目录结构：

src/
├── services/
│   ├── core/                    # 核心业务逻辑
│   │   ├── installation/        # 安装指南服务
│   │   ├── search/             # 搜索提供程序
│   │   └── server/             # MCP 服务器实现
│   ├── providers/              # 外部服务提供程序
│   │   ├── meilisearch/        # Meilisearch 集成
│   │   ├── nacos/              # Nacos 服务发现
│   │   ├── oceanbase/          # OceanBase 向量数据库
│   │   └── offline/            # 离线搜索引擎
│   ├── common/                 # 共享实用工具
│   │   ├── api/                # API 客户端
│   │   ├── cache/              # 缓存机制
│   │   └── vector/             # 向量操作
│   └── interfaces/             # 类型定义
├── types/                      # TypeScript 类型定义
├── utils/                      # 工具函数
└── tests/                      # 测试套件
    ├── unit/                   # 单元测试
    ├── integration/            # 集成测试
    └── e2e/                    # 端到端测试

核心组件

搜索服务层
- 统一搜索接口和提供程序聚合
- 支持多个搜索提供程序并行执行
- 可配置的搜索选项（限制、最小相似度）
搜索提供程序
- Meilisearch 提供程序：使用 Meilisearch 进行向量搜索
- GetMCP 提供程序：从 GetMCP 注册表进行API搜索
- Compass 提供程序：从 Compass 注册表进行API搜索
- Nacos 提供程序：服务发现集成
- 离线提供程序：结合文本和向量的混合搜索
混合搜索策略
- 智能组合文本匹配和向量搜索
- 可配置的权重平衡
- 智能自适应过滤机制
传输层
- Stdio（CLI 默认）
- SSE（Web 集成）
- REST API 端点

有关更详细的架构文档，请参阅 ARCHITECTURE.md。

开发者快速入门

开发环境设置

克隆仓库
安装依赖项：
```
pnpm install
```
构建项目：
```
pnpm run build
```
配置环境变量（参阅快速入门指南）

测试

MCP Advisor 包含全面的测试套件，以确保代码质量和功能。有关单元测试、集成测试、端到端测试和手动测试过程的详细信息，请参阅技术参考。

测试

运行全面测试：

# 运行所有测试
pnpm run check && pnpm run test && pnpm run test:e2e

# 自动化E2E测试脚本
./scripts/run-e2e-test.sh

有关详细测试信息，请参阅技术参考。

库使用

import { SearchService } from '@xiaohui-wang/mcpadvisor';

// 初始化搜索服务
const searchService = new SearchService();

// 搜索MCP服务器
const results = await searchService.search('向量数据库集成');
console.log(results);

传输选项

MCP Advisor 支持多种传输方式：

Stdio 传输（默认）- 适用于命令行工具
SSE 传输 - 适用于 Web 集成
REST 传输 - 提供 REST API 端点

有关更多开发详情，请参阅贡献指南。

贡献指南

我们欢迎对 MCP Advisor 的贡献！

使用示例

示例查询

这里有一些可以与 MCP Advisor 一起使用的示例查询：

"查找用于自然语言处理的MCP服务器"
"文档总结MCP服务器"

示例响应

[
  {
    "标题": "NLP 工具包",
    "描述": "综合性的自然语言处理工具包，具备情感分析、实体识别和文本总结功能。",
    "github_url": "https://github.com/example/nlp-toolkit",
    "相似度": 0.92
  },
  {
    "标题": "文本处理器",
    "描述": "高效的文本处理MCP服务器，支持多语言。",
    "github_url": "https://github.com/example/text-processor",
    "相似度": .85
  }
]

有关更多示例和高级用法，请参阅技术参考。

故障排除

常见问题

连接被拒绝
- 确保服务器正在指定端口上运行
- 检查防火墙设置
没有返回结果
- 尝试一个更一般的查询
- 检查网络连接到注册表API
性能问题
- 考虑添加更具体的搜索词
- 检查服务器资源（CPU/内存）

有关更多故障排除信息，请参阅 TROUBLESHOOTING.md。

搜索提供程序

MCP Advisor 支持多个搜索提供程序，可以同时使用：

Compass 搜索提供程序：使用 Compass API 获取MCP服务器信息
GetMCP 搜索提供程序：使用 GetMCP API 和向量搜索进行语义匹配
Meilisearch 搜索提供程序：使用 Meilisearch 进行快速、容错的文本搜索

有关搜索提供程序的详细信息，请参阅技术参考。

路线图

MCP Advisor 正从一个简单的推荐系统演变为一个智能代理编排平台。我们的愿景是创建一个不仅推荐正确的MCP服务器，而且还能从交互中学习并帮助代理动态规划和执行复杂任务的系统。