在软件开发这个行当里我们经常会有一种深深的无力感。当你接手了一个“祖传”项目，或者试图去理解同事写的一坨复杂逻辑时第一反应往往是找文档。然而现实情况往往是：文档在哪里？或者geng糟糕的是文档在公司的内网里而你的 AI 助手被挡在防火墙之外只Neng干瞪眼。

Zui近，我就陷入了这样的困境。团队内部沉淀了大量的技术文档，全部托管在私有部署的 ShowDoc 上。这些文档是团队的“大脑”，记录了接口定义、架构设计和各种坑的解决方案。但在使用 Claude Code 辅助开发时我不得不进行一种极其原始的“人肉搬运”操作：手动打开浏览器 -> 登录 ShowDoc -> 搜索文档 -> 复制内容 -> 粘贴给 Claude。这不仅打断了我的心流，而且复制粘贴过程中经常会出现格式错乱，让 AI 误解我的意图。

这种重复性的劳动简直是在浪费生命。于是我决定不再妥协，亲自动手撸了一个 ShowDoc MCP 服务器。这不仅仅是一个脚本，它geng像是一座桥梁，让 Claude Code Neng够直接穿透内网限制，读取那些深藏在私有部署环境下的 ShowDoc 文档。今天我就把这套方案的实现细节和踩坑经验毫无保留地分享出来。

为什么我们需要 MCP？

在深入代码之前，我们先来聊聊 MCP。这玩意儿听起来hen高大上，其实你Ke以把它简单理解为 AI 的“插件系统”或者是“万Neng适配器”。以前，AI 模型就像一个被困在孤岛上的天才，它知道hen多理论，但无法直接接触你的本地文件、数据库或者内网服务。

Anthropic 推出的 MCP 协议，就是为了打破这个壁垒。它定义了一套标准，让 AI Neng够安全地通过工具调用外部数据源。对于我们要解决的问题来说MCP 就是那把钥匙，Neng让 Claude 拥有“读取内网文档”的超Neng力。

ShowDoc 私有部署的挑战

ShowDoc 这款工具，在国内技术圈子里还是挺有口碑的。它开源、轻量，非常适合团队内部搭建文档管理系统。hen多公司为了数据安全，dou会选择私有化部署。但这也带来了一个问题：访问权限控制。

私有部署意味着这些文档不在公网上，而且通常需要登录认证才Neng查kan。虽然 ShowDoc 提供了 API 接口，但直接把 API 暴露给 AI 并不安全，而且 AI 也不知道如何处理鉴权逻辑。我们需要一个中间层，既Neng处理复杂的鉴权，又Neng把文档内容“翻译”成 AI Neng读懂的结构化数据。

构建 ShowDoc MCP 服务器：核心思路

我们的目标hen明确：开发一个 MCP 服务，注册一个工具。当用户把一个 ShowDoc 链接扔给 Claude 时这个工具Neng自动解析链接，调用后台 API，把文档内容抓取回来并整理成漂亮的格式呈现给 AI。

先来kankan整个项目的骨架，虽然简单，但五脏俱全：

showdoc-mcp/
├── src/
│   └── index.ts        # 核心逻辑dou在这儿
├── dist/               # TypeScript 编译后的输出目录
├── package.json        # 项目依赖管理
└── tsconfig.json       # TypeScript 配置文件

1. 智Neng解析 URL

这是第一步，也是Zui容易被忽视的一步。ShowDoc 的 URL 格式有点特别，它通常长这样：http://服务器地址/doc/web/#/目录 ID/page_id。注意那个 #，这是前端路由的标志，后端解析时需要特别小心。

我们不Neng指望 AI Neng准确提取出 page_id，所以必须在代码里Zuo足容错处理。我们需要从这一长串字符中，精准地提取出服务器地址和页面 ID。

function parseShowDocUrl: { serverUrl: string; pageId: string } | null {
  // 找到 hash 符号的位置，这是前端路由的分界线
  const hashIndex = url.indexOf;
  if  return null;
  // 截取 base 部分，并去掉多余的路径，得到纯净的服务器地址
  const baseUrl = url.substring;
  const serverUrl = baseUrl.replace;
  // 处理 hash 后面的部分，提取 page_id
  const hashPart = url.substring;
  const segments = hashPart.split;
  // 通常 page_id 在Zui后一位
  const pageId = segments;
  return { serverUrl, pageId };
}

这段代码虽然不长，但解决了一个大麻烦：URL 格式的兼容性。无论用户给的是带 /doc/web 还是不带，我们douNeng正确识别。

2. 调用 ShowDoc API 获取数据

拿到 serverUrl 和 pageId 后真正的重头戏来了——请求 ShowDoc 的接口。这里我们需要用到 ShowDoc 的 user_token，这是访问私有文档的通行证。

我们需要构造一个 POST 请求，参数包括 page_id 和 user_token。这里有个细节，ShowDoc 的 API 地址通常是 /doc/server/index.php?s=/api/page/info。

async function fetchShowDocContent(
  serverUrl: string,
  pageId: string,
  userToken: string
): Promise<{ title: string; content: string; meta?: any }> {
  // 拼接完整的 API 地址
  const apiUrl = `${serverUrl}/doc/server/index.php?s=/api/page/info`;
  // 构造表单数据
  const formData = new URLSearchParams;
  formData.append;
  formData.append;
  try {
    const response = await fetch(apiUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: formData.toString,
    });
    const data = await response.json;
    // 简单的错误处理，防止 API 返回异常时程序崩溃
    if  {
      throw new Error;
    }
    return {
      title: data.data?.page_title || '无标题文档',
      content: data.data?.page_content || '',
      meta: {
        pageId: data.data?.page_id,
        createTime: data.data?.addtime,
        updateTime: data.data?.updatetime,
      },
    };
  } catch  {
    console.error;
    throw error;
  }
}

注意kan，我们不仅返回了文档的标题和正文，还顺手把 meta 信息也带上了。这对于 AI 理解文档的时效性非常有帮助。比如Ru果 AI kan到文档是三年前geng新的，它可Neng会提醒你：“这个信息可NengYi经过时了”。

3. 注册 MCP 工具

有了上面的基础功Neng，Zui后一步就是把它包装成 MCP 工具，注册给 Claude 使用。我们需要告诉 Claude 这个工具叫什么需要什么参数。

server.setRequestHandler => {
  return {
    tools: ,
      },
    }],
  };
});

配置与实战：让 Claude 动起来

代码写好了接下来就是激动人心的配置环节。这一步Ru果走不通，前面的功夫就白费了。

1. 编译与安装

你得把 TypeScript 代码编译成 JavaScript。这没什么好说的，标准操作：

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

2. 配置 Claude Code

这是Zui关键的一步。我们需要修改 Claude 的配置文件，告诉它去哪里找这个 MCP 服务器。

{
  "mcpServers": {
    "showdoc": {
      "command": "node",
      "args": ,
      "cwd": "/path/to/showdoc-mcp",
      "env": {
        "SHOWDOC_TOKEN": "your_api_token_here"
      }
    }
  }
}

这里有几个坑需要特别注意，dou是我踩过的血泪经验：

坑 1：Windows 路径问题 Ru果你是在 Windows 下开发，cwd 路径的写法非常讲究。直接写反斜杠 \ 可Neng会报错。Zui稳妥的写法是使用正斜杠 / 或者双反斜杠 \\。例如："cwd": "E:/project/showdoc-mcp"。

坑 2：Token 安全 虽然示例中把 Token 写这并不是Zui安全的Zuo法。Ru果你的机器有多人使用，建议通过环境变量注入，或者在调用时动态传递。不过对于个人开发环境，这样配置Yi经足够方便了。

效果对比：从“人肉搬运”到“一键直达”

配置完成后那种爽快感是难以言喻的。让我们来kankan前后的对比：

之前：

我：     
我：帮我kankan这个接口怎么定义的？
Claude：好的，我kan到你粘贴了一段文本...

现在：

我：帮我查一下这个文档：http://your-server.com/doc/web/#/123/456
Claude：   
Claude：我Yi经读取了该文档。根据内容，这个接口主要用于...

效率提升不仅仅是时间上的，geng重要的是心流的保持。你不再需要在编辑器和浏览器之间来回切换，所有的交互dou在命令行中完成。而且，因为 MCP 返回的是结构化的数据，Claude 对文档的理解也geng加准确。

进阶思考：不仅仅是读取

虽然我们现在的重点是“读取”，但这套方案的潜力远不止于此。一旦建立了 MCP 这个连接，我们实际上赋予了 AI 操作 ShowDoc 的Neng力。

想象一下未来我们还Ke以 这个工具，增加“创建文档”、“geng新文档”甚至“评论文档”的功Neng。那时候，Claude 就不再只是一个被动的阅读者，而变成了一个Neng主动维护文档的“技术助理”。比如你写完一段代码，Ke以直接告诉 Claude：“把这段代码的注释整理一下geng新到 ShowDoc 的接口文档里。”

技术存在的意义，就是为了解决那些重复、繁琐、打断我们创造力的问题。通过构建这个 ShowDoc MCP 服务器，我们不仅解决了私有文档读取的难题，geng重要的是探索了 AI 与内网工具集成的可Neng性。

当然目前的方案还有优化的空间，比如增加geng复杂的缓存机制、支持 Markdown 渲染优化、或者处理geng复杂的权限逻辑。但这就是技术的魅力所在——永远有下一个问题等着你去解决。

Ru果你也在团队私有化部署中遇到了类似的 AI 访问障碍，希望这篇文章Neng给你提供一些思路。别让 AI 被困在孤岛上，给它造一座桥吧！

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

---