查看“︁Bouffalo MCP”︁的源代码

= Bouffalo SDK Expert — MCP 服务使用指南 =

== 这是什么？ ==

'''Bouffalo SDK Expert''' 是一个 '''MCP（Model Context Protocol）服务'''，为 AI 编程助手提供 Bouffalo SDK 内部知识库的查询能力。

简单来说：你平时写 Bouffalo 芯片代码遇到不会的问题，以前要翻文档、搜 Wiki、问同事。现在可以让 AI 编程助手自动帮你查。

== 它能做什么？ ==

提供 '''3 个工具'''，AI Agent 可以调用：

{| class="wikitable"
! 工具名称 !! 作用 !! 怎么用
|-
| <code>bouffalo_sdk_expert</code> || '''提交问题''' || 用自然语言问一个问题，立即得到一个任务编号（jobId）
|-
| <code>bouffalo_sdk_answer</code> || '''查询结果''' || 拿 jobId 去取答案，AI 会自动轮询直到拿到完整结果（看到 <code><END></code> 说明结束）
|-
| <code>bouffalo_sdk_feedback</code> || '''提交反馈''' || 觉得答案不好用？反馈给后台改进
|}

=== 使用流程 ===
<pre>
你问问题 → AI 调用 bouffalo_sdk_expert → 拿到 jobId
                                                      ↓
AI 反复调用 bouffalo_sdk_answer（轮询）← → 后台在查资料
                                                      ↓
                  拿到完整结果（<END>）→ AI 把答案整理给你
</pre>

== 知识库覆盖范围 ==

知识库收录 Bouffalo SDK '''闭源部分'''的文档，包括：
* 设计架构文档（如 wl80211 WiFi 驱动的四层分层架构）
* API 接口说明
* 错误码描述
* 各类芯片模块（WiFi、蓝牙、外设等）的技术细节

<blockquote>'''注意'''：这个服务查询的是 SDK 内部闭源文档，开源代码不在其覆盖范围内。</blockquote>

----

= 配置指南 — 如何接入 AI 编程助手 =

<blockquote>💡 '''前置准备'''：你需要一个 API Token。如何获取请联系 Bouffalo Lab 内部团队。</blockquote>

== 服务器信息 ==

{| class="wikitable"
! 项目 !! 值
|-
| '''服务器地址''' || <code>https://mcp.bouffalolab.com/mcp</code>
|-
| '''传输协议''' || Streamable HTTP
|-
| '''认证方式''' || Bearer Token（放在 <code>Authorization</code> 请求头里）
|-
| '''MCP 版本''' || 2024-11-05
|}

== 方式一：Claude Code ==

<blockquote>Claude Code 是 Anthropic 的终端 AI 编程助手（非 Claude Desktop 桌面版）。</blockquote>

=== 📍 配置文件位置 ===

{| class="wikitable"
! 场景 !! 文件 !! 适用范围
|-
| 所有项目都用 || <code>~/.claude.json</code> || 个人全局
|-
| 单个项目用 || 项目根目录下新建 <code>.mcp.json</code> || 仅该项目
|}

=== 📝 配置内容 ===

在你的 <code>.mcp.json</code> 或 <code>~/.claude.json</code> 中添加：

<syntaxhighlight lang="json">
{
  "mcpServers": {
    "bouffalo-sdk-expert": {
      "type": "http",
      "url": "https://mcp.bouffalolab.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
      }
    }
  }
}
</syntaxhighlight>

<blockquote>⚠️ 如果你把 <code>.mcp.json</code> 提交到 Git，请不要把 Token 写死在文件里。使用环境变量：</blockquote>

<syntaxhighlight lang="json">
{
  "mcpServers": {
    "bouffalo-sdk-expert": {
      "type": "http",
      "url": "https://mcp.bouffalolab.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BOUFFALO_API_TOKEN}"
      }
    }
  }
}
</syntaxhighlight>

然后在使用前设置环境变量：
<syntaxhighlight lang="bash">
export BOUFFALO_API_TOKEN="你的Token"
</syntaxhighlight>

=== ✅ 验证是否成功 ===

打开 Claude Code，输入 <code>/mcp</code> 查看 MCP 服务器列表。如果看到 <code>bouffalo-sdk-expert</code> 状态正常，就可以开始问 Bouffalo 相关的问题了。

== 方式二：Codex CLI ==

<blockquote>Codex CLI 是 OpenAI 的终端 AI 编程助手，使用 TOML 格式配置。</blockquote>

=== 📍 配置文件位置 ===

{| class="wikitable"
! 场景 !! 文件 !! 适用范围
|-
| 所有项目都用 || <code>~/.codex/config.toml</code> || 个人全局
|-
| 单个项目用 || 项目根目录 <code>.codex/config.toml</code> || 仅该项目
|}

=== 📝 配置内容 ===

在配置文件中添加：

<syntaxhighlight lang="toml">
[mcp_servers.bouffalo_sdk_expert]
url = "https://mcp.bouffalolab.com/mcp"
bearer_token_env_var = "BOUFFALO_API_TOKEN"
startup_timeout_sec = 15
tool_timeout_sec = 60
</syntaxhighlight>

<blockquote>💡 <code>bearer_token_env_var</code> 指定环境变量名，Codex 会自动读取并添加 <code>Authorization: Bearer &lt;value&gt;</code> 头。无需手动写 <code>Authorization</code> 头。</blockquote>

使用前设置环境变量：
<syntaxhighlight lang="bash">
export BOUFFALO_API_TOKEN="你的Token"
</syntaxhighlight>

=== ✅ 验证是否成功 ===

在 Codex 中输入 <code>/mcp</code>，确认 <code>bouffalo_sdk_expert</code> 出现在服务器列表中且状态正常。

== 方式三：OpenCode ==

<blockquote>OpenCode 是开源 AI 编程助手，配置文件支持 JSON / JSONC 格式。</blockquote>

=== 📍 配置文件位置 ===

{| class="wikitable"
! 场景 !! 文件 !! 适用范围
|-
| 所有项目都用 || <code>~/.config/opencode/opencode.json</code> || 个人全局
|-
| 单个项目用 || 项目根目录 <code>opencode.json</code> || 仅该项目
|}

=== 📝 配置内容 ===

<syntaxhighlight lang="jsonc">
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bouffalo_sdk_expert": {
      "type": "remote",
      "url": "https://mcp.bouffalolab.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
      },
      "timeout": 60000
    }
  }
}
</syntaxhighlight>

使用环境变量（推荐）：

<syntaxhighlight lang="jsonc">
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bouffalo_sdk_expert": {
      "type": "remote",
      "url": "https://mcp.bouffalolab.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:BOUFFALO_API_TOKEN}"
      },
      "timeout": 60000
    }
  }
}
</syntaxhighlight>

<blockquote>💡 OpenCode 的环境变量语法是 <code>{env:变量名}</code>，和 Claude Code 的 <code>${变量名}</code> 不同，注意区分。</blockquote>

=== ✅ 验证是否成功 ===

打开 OpenCode，看启动日志中 MCP 服务器连接状态，确认 <code>bouffalo_sdk_expert</code> 连接成功。

----

= 使用示例 =

配置完成后，你可以直接用自然语言向 AI 助手提问：

<blockquote>
"Bouffalo SDK 中 wifi_mgmr 的初始化流程是什么？"<br />
"wl80211 驱动中 STA 模式的连接状态机有几个状态？"<br />
"请解释 wl80211 的 RX 数据路径，从硬件中断到应用层 socket"
</blockquote>

AI 助手会自动调用 <code>bouffalo_sdk_expert</code> 查询知识库，然后轮询 <code>bouffalo_sdk_answer</code> 获取结果，最后整理成易读的答案给你。

----

= 常见问题 =

; Q: 提示 "任务已提交" 后没反应了？
: A: AI 助手需要多次调用 <code>bouffalo_sdk_answer</code> 来轮询结果。如果长时间没反应，可以提醒 AI "请用 bouffalo_sdk_answer 查询 jobId xxx 的结果"。

; Q: 提示 "未找到任务，可能已过期"？
: A: 任务超时被清理了，重新提交问题即可。

; Q: Token 怎么获取？
: A: 请联系 Bouffalo Lab [mailto:zrrong@bouffalolab.com 内部团队]获取 API Token。邮件中请提供 '''公司名''' 。

; Q: 答案不够详细或缺少某些内容？
: A: 可以让 AI 调用 <code>bouffalo_sdk_feedback</code> 提交反馈，后台团队会据此迭代改进。

; Q: 支持中文问题吗？
: A: 完全支持。知识库文档大部分是中文的，用中文提问效果最好。