Counsel MCP Server

Counsel MCP 服务

一个开源的 Model Context Protocol (MCP) 服务，可将 AI Agent 连接到 Counsel API，以进行战略推理和多视角分析。

功能

• 托管与可自托管 - 即刻使用托管服务，也可以运行自己的实例
• 战略推理 - 使用 Counsel 的辩论和多视角推理引擎
• 顾问会话 - 运行交互式信息收集和个人资料调整会话
• 原生 OAuth 2.0 - 标准 MCP 身份验证由客户端自动处理
• 双传输模式 - STDIO 适用于本地客户端，HTTP 适用于 Web 客户端和共享服务

目录

• 快速开始（托管版）
• 安装（自托管）
  • Claude Desktop
  • Claude Code（CLI）
  • Cursor
  • Windsurf
  • VS Code with Copilot
  • 其他 MCP 客户端
• 身份验证
• 可用工具
• 使用示例
• 配置
• 故障排除
• 开发
• 贡献
• 许可证

快速开始（托管版）

无需安装，即可立即连接到托管的 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：

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

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

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"
      }
    }
  }
}

带 OAuth 的 HTTP 模式

对于支持通过 OAuth 2.0 进行 HTTP 传输的客户端，请单独运行服务：

# Start the HTTP server
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_API_KEY 环境变量，并填入从 counsel.getmason.dev 获取的 API 密钥：

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

启动一场新的战略咨询（辩论），从多个角度分析复杂问题。

示例：

Start a consultation about "Should we migrate our monolith to microservices?"
with context about our 50-person engineering team and mode set to deep

get_consultation_status

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

get_consultation_report

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

list_consultations

列出你过去的咨询。

sharpen_question

在开始咨询前，优化并完善战略问题。

示例：

Sharpen this question: "Is AI good for our company?"

consult_advisor

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

使用示例

战略决策

Use Counsel to analyze: "Should we expand into the European market in 2025?"

Consider these stakeholders: CEO, CFO, Head of Sales, Legal
Use deep analysis mode

问题优化

Use the sharpen_question tool to improve this question:
"How do we fix our culture?"

Context: We're a 200-person startup experiencing rapid growth

查看咨询进度

Check the status of consultation abc-123-def

配置

环境变量

CLI 命令

# STDIO mode (default) - for most MCP clients
npx -y counsel-mcp-server start

# HTTP mode - for clients supporting OAuth
npx -y counsel-mcp-server http [options]

HTTP Options:
  -p, --port <port>  Port to listen on (default: 3000)
  --host <host>      Host to bind to (default: localhost)

故障排除

“未找到工具”错误

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

身份验证问题

1. 检查你是否拥有有效的 Counsel 账户
2. 尝试移除并重新添加 MCP 服务配置
3. 如果客户端支持，请清除其 MCP 缓存

连接被拒绝

如果在 HTTP 模式下运行，请确保：

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

服务无法启动

# Check Node.js version (requires 18+)
node --version

# Try running directly to see errors
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            # Compile TypeScript
npm run dev              # Watch mode
npm run start            # Run server
npm test                 # Run tests
npm run lint             # Type check
npm run security:check   # Scan staged files for secrets
npm run security:check:all  # Scan all files for secrets

安全

本项目包含自动化密钥检测：

• 提交前钩子：在每次提交前自动扫描暂存文件
• CI 集成：在所有拉取请求中运行安全检查
• 模式检测：AWS 密钥、GitHub 令牌、API 密钥、私钥等

详情请参阅 CONTRIBUTING.md。

项目结构

src/
├── index.ts        # HTTP server, OAuth proxy, MCP transport
├── client.ts       # API client with request-scoped auth
├── config.ts       # Environment configuration
└── tools/
    ├── debates.ts  # Consultation tools
    └── advisor.ts  # Advisor session tools

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

快速开始

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

许可证

MIT 许可证 - 详情请参阅 LICENSE。

链接

• Counsel Platform - 战略推理平台
• MCP Specification - Model Context Protocol 文档
• GitHub Issues - 报告错误或请求功能
• GitHub Discussions - 提出问题