Counsel MCP

🚀 Counsel MCP 服务器

Counsel MCP 服务器是一个开源的 模型上下文协议 (MCP) 服务器，它能将 AI 代理连接到 Counsel API，以进行战略推理和多视角分析。

✨ 主要特性

• 托管与自托管模式：可立即使用托管服务器，也能自行运行实例。
• 战略推理：访问 Counsel 的辩论和多视角推理引擎。
• 顾问会话：运行交互式信息收集和配置文件调整会话。
• 原生 OAuth 2.0：客户端自动处理标准 MCP 身份验证。
• 双传输模式：本地客户端使用 STDIO，Web 客户端和共享服务器使用 HTTP。

🚀 快速开始

托管模式

无需安装，可立即连接到托管的 Counsel MCP 服务器：

http://counsel-mcp.getmason.dev/mcp

对于支持 HTTP 传输的 MCP 客户端，只需添加以下配置：

{
  "mcpServers": {
    "counsel": {
      "url": "http://counsel-mcp.getmason.dev/mcp",
      "transport": "http"
    }
  }
}

OAuth 身份验证由 MCP 客户端自动处理。

📦 安装指南

自托管模式

可在本地运行自己的 Counsel MCP 服务器实例。

前提条件

1. 系统已安装 Node.js 18+。
2. 在 counsel.getmason.dev 拥有 Counsel 账户。

Claude Desktop

将以下配置添加到 claude_desktop_config.json 文件中：

Claude Code (CLI)

claude mcp add counsel -- npx -y counsel-mcp-server start

或者手动添加到 MCP 设置中：

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

Cursor

将以下配置添加到 Cursor MCP 配置文件（项目或全局设置中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

Windsurf

将以下配置添加到 Windsurf MCP 配置文件：

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

VS Code with Copilot

将以下配置添加到 VS Code 设置文件 (settings.json)：

{
  "mcp.servers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"]
    }
  }
}

其他 MCP 客户端

服务器支持两种传输模式，可根据客户端功能选择：

STDIO 模式（默认）

大多数 MCP 客户端使用 STDIO 传输，配置如下：

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"],
      "env": {
        "COUNSEL_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP 模式（带 OAuth）

对于支持带 OAuth 2.0 的 HTTP 传输的客户端，需单独运行服务器：

# 启动 HTTP 服务器
npx -y counsel-mcp-server http --port 3000

此命令将启动一个 HTTP 服务器，具有以下端点：

• MCP 端点：http://localhost:3000/mcp
• OAuth 发现：http://localhost:3000/.well-known/oauth-authorization-server 然后配置客户端进行连接：

{
  "mcpServers": {
    "counsel": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

HTTP 模式使用 OAuth 2.0 进行自动令牌管理，无需 API 密钥。

传输模式比较

🔐 身份验证

服务器支持两种身份验证模式：

STDIO 模式（默认）

从 counsel.getmason.dev 获取 API 密钥，并设置 COUNSEL_API_KEY 环境变量：

export COUNSEL_API_KEY=your_api_key_here

或者将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "counsel": {
      "command": "npx",
      "args": ["-y", "counsel-mcp-server", "start"],
      "env": {
        "COUNSEL_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP 模式（OAuth 2.0）

当以 HTTP 模式运行时（npx -y counsel-mcp-server http），身份验证通过 OAuth 2.0 自动处理：

1. 首次使用 Counsel 工具时，MCP 客户端将提示进行身份验证。
2. 会被重定向到使用 Counsel 账户登录。
3. 授权后，令牌将自动管理。 在 HTTP 模式下 无需手动设置 API 密钥，MCP 客户端会处理整个 OAuth 流程。

OAuth 端点（HTTP 模式）

服务器提供标准的 OAuth 2.0 端点：

🛠️ 可用工具

start_consultation

启动新的战略咨询（辩论），以多视角分析复杂问题。

针对“我们是否应该在 2025 年将单体应用迁移到微服务？”启动咨询，提供关于我们 50 人工程团队的上下文，并将模式设置为深度分析

get_consultation_status

检查正在进行的咨询的状态。

get_consultation_report

从已完成的咨询中获取最终综合报告。

list_consultations

列出过去的咨询。

sharpen_question

在启动咨询之前完善和改进战略问题。

完善这个问题：“人工智能对我们公司有好处吗？”

consult_advisor

启动交互式顾问会话，用于头脑风暴或问题界定。

💻 使用示例

战略决策

使用 Counsel 分析：“我们是否应该在 2025 年拓展欧洲市场？”
考虑这些利益相关者：CEO、CFO、销售主管、法务
使用深度分析模式

问题完善

使用 sharpen_question 工具完善这个问题：
“我们如何改善公司文化？”
上下文：我们是一家 200 人的初创公司，正在经历快速增长

检查咨询进度

检查咨询 abc-123-def 的状态

⚙️ 配置

环境变量

CLI 命令

# STDIO 模式（默认） - 适用于大多数 MCP 客户端
npx -y counsel-mcp-server start

# HTTP 模式 - 适用于支持 OAuth 的客户端
npx -y counsel-mcp-server http [选项]

HTTP 选项:
  -p, --port <port>  监听端口（默认：3000）
  --host <host>      绑定的主机（默认：localhost）

🐞 故障排除

“工具未找到”错误

确保 MCP 服务器在客户端中配置正确。添加配置后重启客户端。

身份验证问题

1. 检查是否拥有有效的 Counsel 账户。
2. 尝试删除并重新添加 MCP 服务器配置。
3. 如果可用，清除客户端的 MCP 缓存。

连接被拒绝

如果以 HTTP 模式运行，确保：

• 服务器正在运行（npx counsel-mcp-server start）。
• 端口未被防火墙阻止。
• 没有其他进程使用相同的端口。

服务器无法启动

# 检查 Node.js 版本（需要 18+）
node --version

# 尝试直接运行以查看错误信息
npx counsel-mcp-server start

调试模式

如需详细日志记录，可检查 MCP 客户端的日志，或直接在终端中运行服务器以查看输出。

🛠️ 开发

前提条件

• Node.js 18+
• npm 9+

环境搭建

git clone https://github.com/mercurialsolo/counsel-mcp.git
cd counsel-mcp-server
npm install
npm run build

命令

npm run build            # 编译 TypeScript
npm run dev              # 监听模式
npm run start            # 运行服务器
npm test                 # 运行测试
npm run lint             # 类型检查
npm run security:check   # 扫描暂存文件中的敏感信息
npm run security:check:all  # 扫描所有文件中的敏感信息

安全

本项目包含自动敏感信息检测：

• 预提交钩子：每次提交前自动扫描暂存文件。
• CI 集成：所有拉取请求都会运行安全检查。
• 模式检测：检测 AWS 密钥、GitHub 令牌、API 密钥、私钥等。 详情请参阅 CONTRIBUTING.md。

项目结构

src/
├── index.ts        # HTTP 服务器、OAuth 代理、MCP 传输
├── client.ts       # 带有请求范围身份验证的 API 客户端
├── config.ts       # 环境配置
└── tools/
    ├── debates.ts  # 咨询工具
    └── advisor.ts  # 顾问会话工具

🤝 贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

快速开始

1. 分叉仓库。
2. 创建功能分支：git checkout -b feature/your-feature。
3. 进行更改并添加测试。
4. 运行 npm test 确保测试通过。
5. 提交拉取请求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

🔗 链接

• Counsel 平台 - 战略推理平台
• MCP 规范 - 模型上下文协议文档
• GitHub 问题 - 报告 bug 或请求功能
• GitHub 讨论 - 提问