Claude Code 读取私有 ShowDoc 文档

开发MCP服务：让 Claude Code 读取私有 ShowDoc 文档

前言

团队内部用 ShowDoc 写了大量技术文档，但都是私有部署，外面访问不到。

最近在用 Claude Code 辅助开发时，我经常需要查这些内部文档。每次都要：

手动打开 ShowDoc 找文档
复制内容粘贴给 Claude
反复切换窗口，效率很低

于是我开发了一个 ShowDoc MCP 服务器，让 Claude Code 可以直接读取私有 ShowDoc 文档。

什么是 MCP

MCP（Model Context Protocol） 是 Anthropic 推出的协议，让 AI 能够安全地访问外部数据源和工具。

简单理解：MCP 就是 AI 的「插件系统」。

核心功能

这个 MCP 服务器实现了一个工具：get_showdoc_content

功能：通过 ShowDoc URL 自动获取文档内容，包括标题、正文、元信息（创建时间、更新时间等）

使用方式：

ruby 复制代码

帮我查一下这个文档：http://your-server.com/doc/web/#/3/2587

Claude 会自动调用 MCP 工具获取文档内容，无需手动复制粘贴。

技术实现

项目结构

bash 复制代码

showdoc-mcp/
├── src/
│   └── index.ts        # 核心实现
├── dist/               # 编译输出
├── package.json
└── tsconfig.json

核心代码

1. URL 解析

ShowDoc URL 格式：http://服务器地址/doc/web/#/目录 ID/page_id

typescript 复制代码

function parseShowDocUrl(url: string): { serverUrl: string; pageId: string } | null {
  const hashIndex = url.indexOf('#');
  if (hashIndex === -1) return null;

  // 提取服务器地址
  const baseUrl = url.substring(0, hashIndex);
  const serverUrl = baseUrl.replace('/doc/web/', '');

  // 提取 page_id
  const hashPart = url.substring(hashIndex + 1);
  const segments = hashPart.split('/');
  const pageId = segments[segments.length - 1];

  return { serverUrl, pageId };
}

2. 调用 ShowDoc API

typescript 复制代码

async function fetchShowDocContent(
  serverUrl: string,
  pageId: string,
  userToken: string
): Promise<{ title: string; content: string; meta?: any }> {
  const apiUrl = `${serverUrl}/doc/server/index.php?s=/api/page/info`;

  const formData = new URLSearchParams();
  formData.append('page_id', pageId);
  formData.append('user_token', userToken);

  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: formData.toString(),
  });

  const data = await response.json();
  
  return {
    title: data.data?.page_title || 'Untitled',
    content: data.data?.page_content || '',
    meta: {
      pageId: data.data?.page_id,
      createTime: data.data?.addtime,
      updateTime: data.data?.updatetime,
    },
  };
}

3. MCP 工具定义

typescript 复制代码

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: 'get_showdoc_content',
      description: '从 ShowDoc 链接获取文档内容',
      inputSchema: {
        type: 'object',
        properties: {
          url: { type: 'string', description: 'ShowDoc 文档链接' },
          user_token: { type: 'string', description: '用户认证 token' },
        },
        required: ['url'],
      },
    }],
  };
});

配置使用

1. 安装构建

bash 复制代码

git clone https://github.com/yc-lm/showdoc-mcp
cd showdoc-mcp
npm install
npm run build

2. 配置 Claude Code

在 ~/.claude.json 中添加：

json 复制代码

{
  "mcpServers": {
    "showdoc": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/showdoc-mcp",
      "env": {
        "SHOWDOC_TOKEN": "your_api_token_here"
      }
    }
  }
}

注意：cwd 改为你的实际项目路径

3. 获取 ShowDoc Token

在 ShowDoc 系统中：

登录 ShowDoc
进入「个人设置」页面
找到「API 密钥」或「user_token」字段

4. 使用示例

ruby 复制代码

# 直接给 Claude 发 ShowDoc 链接
帮我查一下这个文档：http://your-server.com/doc/web/#/3/2587

Claude 会自动调用 get_showdoc_content 工具获取文档内容。

设计亮点

1. 双 Token 配置方式

方式一：环境变量（推荐）

json 复制代码

{
  "env": { "SHOWDOC_TOKEN": "your_token" }
}

方式二：调用时传参

makefile 复制代码

url: http://...
user_token: your_token

灵活适配不同场景：团队共享用环境变量，个人临时用传参。

2. URL 自动解析

用户只需粘贴完整的 ShowDoc 链接，MCP 服务器自动解析出：

服务器地址
Page ID

无需用户手动提取参数。

3. 完整的错误处理

typescript 复制代码

// URL 格式校验
if (!parsed) {
  return {
    content: [{ type: 'text', text: '错误：URL 格式不正确' }],
    isError: true,
  };
}

// Token 校验
if (!user_token) {
  return {
    content: [{ type: 'text', text: '错误：缺少 user_token' }],
    isError: true,
  };
}

// API 错误处理
if (data.error_code !== 0) {
  throw new Error(`ShowDoc API error: ${data.error_message}`);
}

4. 返回结构化元信息

不仅返回文档内容，还附带：

Page ID
创建时间
更新时间

方便 AI 理解文档的时效性和上下文。

实际效果

之前：

css 复制代码

我：[手动打开 ShowDoc] [找到文档] [复制内容] [粘贴给 Claude]
我：帮我看看这个文档说的什么
Claude：好的，我来分析...

现在：

ini 复制代码

我：帮我查一下这个文档：http://your-server.com/doc/web/#/3/2587
Claude：[自动调用 MCP 工具] [获取文档内容] [直接分析]

效率提升明显，而且避免了手动复制可能出现的格式错乱问题。

使用截图

1.配置成功 2.获取文档内容成功

踩坑记录

坑 1：Windows 路径配置

问题：MCP 配置中的 cwd 路径在 Windows 下不识别

解决：Windows 路径使用正斜杠 / 或双反斜杠 \\

json 复制代码

"cwd": "E:/project/showdoc-mcp"
// 或
"cwd": "E:\\project\\showdoc-mcp"

坑 2：Token 安全

问题：Token 硬编码在配置文件中，容易泄露

解决：

推荐用环境变量配置
.gitignore 忽略包含 Token 的文件
团队共享时用配置管理工具分发

坑 3：URL 解析边界情况

问题：ShowDoc URL 格式 variations 多，容易解析失败

解决：增加多种格式兼容，提取关键信息（服务器地址 + page_id）即可

源码地址

github.com/yc-lm/showd...

小结

这个 MCP 服务器的核心价值：

✅ 让 AI 直接访问私有文档系统
✅ 减少手动复制粘贴，提升效率
✅ 保持文档格式完整，避免信息丢失
✅ 配置简单，易于团队推广

对于重度依赖内部文档的团队，这类 MCP 工具可以显著提升 AI 辅助开发的体验。

你们团队用什么文档系统？有没有类似的需求？欢迎留言交流～ 👇