@ztmy/odocs-mcp

v1.0.11

Published

a month ago

石墨文档MCP服务器 - 支持SSO登录和文档内容读取的MCP协议实现

0High
0Medium
0Low

ztmy

shimo 石墨文档 odocs document

🚀 odocs-mcp

石墨文档 & 研发云需求 MCP 服务器 - 让 AI 助手轻松访问企业文档和需求信息

项目源码：https://oneteam.myoas.com/micro-app/ocode-na/80398900/odocs-mcp/overview

📖 简介

odocs-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，专为石墨文档（Shimmer Docs）和研发云需求集成而设计。它使 AI 助手能够通过 SSO 认证安全地访问企业文档和需求信息，并将内容转换为 Markdown 格式，为 AI 工作流提供数据支持。

通过这个 MCP 服务器，您可以在 Cursor、Claude Desktop 等支持 MCP 协议的 AI 客户端中，直接与石墨文档和研发云需求进行交互，无需手动复制粘贴内容。

项目参考：本项目设计理念和实现方式参考了 AI-Test Hub 的企业 AI 工具集成最佳实践。

✨ 核心特性

🔐 企业 SSO 认证：支持企业级单点登录，确保文档访问安全
📄 智能文档解析：将石墨文档内容转换为结构化 Markdown 格式
📋 研发云需求读取：获取需求详情、评论、技术方案，自动提取关联石墨文档
🖼️ 图片资源处理：自动下载并本地化文档中的图片资源
💾 会话状态管理：智能管理登录凭证，支持自动刷新
🔄 实时同步：获取文档最新内容，保持数据时效性
🛠️ 标准 MCP 协议：完全兼容 MCP 规范，易于集成

📦 安装与使用

在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加以下配置：

{
  "mcpServers": {
    "odocs-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@boji/odocs-mcp@latest"
      ],
      "env": {
        "npm_config_registry": "http://admin.npm.oppoer.me"
      }
    }
  }
}

如果 Cursor 中提示 Error，可尝试清除 npm 缓存，再重新导入 cursor

npm cache clean --force
npx clear-npx-cache

🎯 使用示例

在 AI 对话中调用 MCP 工具

配置完成后，您可以在 Cursor 或其他支持 MCP 的 AI 客户端中直接使用以下命令：

登录认证

请登录石墨文档

AI 会自动调用 sso_login 工具进行 SSO 认证。正常情况直接读取文档即可，会自动触发登录流程。触发登录时，会通过浏览器打开 sso 认证网页，请在 2 分钟内完成登录。

读取文档内容

请读取这个石墨文档的内容：https://odocs.myoas.com/docs/e1Az42L705UVj4qW

AI 会使用 read_odocs 工具获取文档内容。如果当前未登录或登录已过期，系统会自动触发 SSO 登录流程，确保文档访问权限有效。

带图片的文档读取

请读取这个石墨文档的内容：https://odocs.myoas.com/docs/e1Az42L705UVj4qW，结合图片内容对文档进行总结

AI 会调用 read_odocs 并设置 saveImages: true 参数。若选用的大模型支持图片，会通过 Read 工具自动识别图片信息。若不特意注明，mcp 工具默认不会获取文档中的图片。

读取研发云需求

请读取这个研发云需求的内容：https://oneteam.myoas.com/micro-app/noah-coteam/requirement/detail?projectId=12345&requireId=67890

AI 会使用 read_devops_requirement 工具获取需求详情、评论、技术方案等信息。默认会自动下载需求中的图片，并读取需求详情和技术方案中关联的石墨文档。

读取需求并分析关联文档

请读取这个需求，帮我整理需求详情和技术方案的关键信息：https://oneteam.myoas.com/micro-app/noah-coteam/requirement/detail?projectId=12345&requireId=67890

工具会自动识别需求中关联的石墨文档链接，下载并保存到本地。返回结果中会包含所有文件的完整路径，AI 可通过 read_file 工具读取关联的石墨文档内容。

读取研发云Bug

请读取这个研发云Bug的内容：https://oneteam.myoas.com/micro-app/noah-coteam/bugList/list?projectId=123&projectType=1&bugId=456

AI 会使用 read_devops_bug 工具获取Bug详情、评论和附件。默认会自动下载图片和附件，并自动解压压缩包类型的附件。

检查系统状态

检查石墨文档MCP服务的状态

AI 会使用 check_status 或 get_config 工具。

环境变量配置

Cursor配置env

可在 Cursor 配置中的 env 字段设置以下完整环境变量：

{
  "mcpServers": {
    "odocs-mcp": {
      "command": "npx",
      "args": ["-y", "odocs-mcp@latest"],
      "env": {
        "npm_config_registry": "http://admin.npm.oppoer.me",
        
        "// 石墨文档配置": "",
        "ODOCS_PLATFORM_URL": "https://your-shimmer-platform.com",
        "ODOCS_SSO_BASE_URL": "https://your-sso-server.com/api/extensions/auth",
        "ODOCS_SSO_ENTRY_URL": "https://your-shimmer-platform.com/odoc/link/sso",
        
        "// 通用配置": "",
        "ODOCS_OUTPUT_DIR": "~/.odocs-mcp/exports",
        "ODOCS_CREDENTIALS_PATH": "~/.odocs-mcp/credentials.json",
        "ODOCS_REQUEST_TIMEOUT": "30000",
        "ODOCS_COOKIE_TTL": "1800000",
        "ODOCS_COOKIE_REFRESH_BUFFER": "300000",
        
        "// 研发云配置": "",
        "ODOCS_DEVOPS_ENTRY_URL": "https://oneteam.myoas.com/basic/v1/login/grug4a?url=...",
        "ODOCS_DEVOPS_API_BASE": "https://oneteam.myoas.com",
        "ODOCS_DEVOPS_COOKIE_TTL": "1800000",
        "ODOCS_DEVOPS_COOKIE_REFRESH_BUFFER": "300000"
      }
    }
  }
}

配置说明

石墨文档配置

| 环境变量 | 说明 | 默认值 | |----------|------|--------| | ODOCS_PLATFORM_URL | 石墨文档平台地址 | https://odocs.myoas.com | | ODOCS_SSO_BASE_URL | SSO 认证 API 基础地址 | https://llmgencase.oppoer.me/api/extensions/auth | | ODOCS_SSO_ENTRY_URL | SSO 登录入口地址 | 内置默认值 |

通用配置

| 环境变量 | 说明 | 默认值 | |----------|------|--------| | ODOCS_OUTPUT_DIR | 文档导出根目录 | ~/.odocs-mcp/exports | | ODOCS_CREDENTIALS_PATH | 凭证文件存储路径 | ~/.odocs-mcp/credentials.json | | ODOCS_TEMP_DIR | 临时文件目录 | 系统临时目录 | | ODOCS_REQUEST_TIMEOUT | HTTP 请求超时时间（毫秒） | 30000 (30秒) | | ODOCS_LOGIN_POLL_TIMEOUT | SSO 登录轮询超时时间（毫秒） | 120000 (2分钟) | | ODOCS_LOGIN_POLL_INTERVAL | SSO 登录轮询间隔（毫秒） | 2000 (2秒) | | ODOCS_COOKIE_TTL | Cookie 有效期（毫秒） | 1800000 (30分钟) | | ODOCS_COOKIE_REFRESH_BUFFER | Cookie 提前刷新时间（毫秒） | 300000 (5分钟) | | ODOCS_SSO_REFRESH_BUFFER | SSO Token 提前刷新时间（毫秒） | 300000 (5分钟) | | ODOCS_USER_AGENT | 自定义 User-Agent 字符串 | odocs-mcp/1.0.0 |

研发云配置

| 环境变量 | 说明 | 默认值 | |----------|------|--------| | ODOCS_DEVOPS_ENTRY_URL | 研发云 SSO 登录入口 URL | 内置默认值 | | ODOCS_DEVOPS_API_BASE | 研发云 API 基础地址 | https://oneteam.myoas.com | | ODOCS_DEVOPS_CSRF_TOKEN_NAME | CSRF Token Cookie 名称 | cloud_portal_csrftoken | | ODOCS_DEVOPS_COOKIE_TTL | 研发云 Cookie 有效期（毫秒） | 1800000 (30分钟) | | ODOCS_DEVOPS_COOKIE_REFRESH_BUFFER | 研发云 Cookie 提前刷新时间（毫秒） | 300000 (5分钟) | | ODOCS_DEVOPS_REQUIREMENT_DETAIL_URL | 需求详情 API 路径 | /noah-coteam-api/api/coop/workItem/query | | ODOCS_DEVOPS_REQUIREMENT_COMMENTS_URL | 需求评论 API 路径 | /noah-coteam-api/api/coop/comment/list | | ODOCS_DEVOPS_PROJECT_INFO_URL | 项目信息 API 路径 | /noah-coteam-api/api/coop/project/query/info | | ODOCS_DEVOPS_DELIVER_LIST_URL | 交付件列表 API 路径 | /release-plan-api/change/v1/deliver/list | | ODOCS_DEVOPS_BUG_DETAIL_URL | Bug详情 API 路径 | /noah-coteam-api/api/coop/workItem/query | | ODOCS_DEVOPS_BUG_COMMENTS_URL | Bug评论 API 路径 | /noah-coteam-api/api/coop/comment/list | | ODOCS_DEVOPS_BUG_ATTACHMENTS_URL | Bug附件列表 API 路径 | /noah-coteam-api/api/coop/attachment/list/query | | ODOCS_DEVOPS_BUG_ATTACHMENT_PRESIGNED_URL | Bug附件预签名URL API 路径 | /noah-coteam-api/api/coop/attachment/getPresignedUrl |

🔧 MCP 工具 API 参考

认证相关

`sso_login`

执行 SSO 单点登录认证

参数:

checkStatus (boolean, 可选): 仅检查当前登录状态，不执行登录流程

示例:

// 执行登录
await sso_login()

// 检查登录状态
await sso_login({ checkStatus: true })

`sso_logout`

登出并清除所有已保存的登录凭证

文档操作

`read_odocs`

读取石墨文档内容并转换为 Markdown 格式

参数:

url (string, 必需): 石墨文档的完整 URL
saveImages (boolean, 可选): 是否下载并本地化图片，默认 false
outputDir (string, 可选): 自定义输出目录路径
exportType (string, 可选): 导出格式，支持 md/docx/pdf，默认 md
useExport (boolean, 可选): 是否使用导出 API，默认 false 使用本地解析

示例:

// 基本文档读取
await read_odocs({ url: "https://odocs.myoas.com/docs/abc123" })

// 包含图片下载
await read_odocs({ 
  url: "https://odocs.myoas.com/docs/abc123", 
  saveImages: true 
})

`read_devops_requirement`

读取研发云需求信息，返回 Markdown 格式。支持获取需求详情、评论、技术方案，并可自动提取关联的石墨文档。

参数:

| 参数名 | 类型 | 必需 | 默认值 | 说明 | | ----------------------- | ------- | ---- | -------- | -------------------------------- | | url | string | ✅ | - | 研发云需求链接 | | saveImages | boolean | ❌ | true | 是否下载需求中的图片到本地 | | includeComments | boolean | ❌ | true | 是否包含需求评论 | | includeTechSolution | boolean | ❌ | true | 是否包含技术方案（交付件） | | fetchDetailOdocs | boolean | ❌ | true | 是否自动读取需求详情中的石墨文档 | | fetchTechOdocs | boolean | ❌ | true | 是否自动读取技术方案中的石墨文档 | | outputDir | string | ❌ | 配置目录 | 自定义输出目录路径 |

返回内容:

需求基本信息（ID、标题、项目名称等）
需求详情 HTML 内容
需求评论列表
技术方案链接列表
关联石墨文档的本地路径
下载的图片路径列表

输出目录结构:

需求标题_时间/
├── requirement_projectId_requireId.md  # 主需求文件
├── images/                              # 需求中的图片
│   ├── req_xxx_0.png
│   └── req_xxx_1.png
└── odocs/                               # 关联的石墨文档
    ├── 文档1标题/
    │   └── 文档1标题.md
    └── 文档2标题/
        └── 文档2标题.md

示例:

// 基本需求读取（使用默认参数，自动读取关联石墨文档）
await read_devops_requirement({ 
  url: "https://oneteam.myoas.com/micro-app/noah-coteam/requirement/detail?projectId=123&requireId=456" 
})

// 仅读取需求，不读取关联石墨文档
await read_devops_requirement({ 
  url: "https://oneteam.myoas.com/micro-app/noah-coteam/requirement/detail?projectId=123&requireId=456",
  fetchDetailOdocs: false,
  fetchTechOdocs: false
})

// 完整读取（包含所有关联内容）
await read_devops_requirement({ 
  url: "https://oneteam.myoas.com/micro-app/noah-coteam/requirement/detail?projectId=123&requireId=456",
  saveImages: true,
  includeComments: true,
  includeTechSolution: true,
  fetchDetailOdocs: true,
  fetchTechOdocs: true
})

返回结果示例:

## 📋 需求标题

**需求ID**: 456
**项目ID**: 123
**项目名称**: 示例项目

---

### 📁 输出目录信息（重要）

> ⚠️ **注意**：以下文件路径信息用于后续读取关联文档，请使用 `read_file` 工具读取时使用**完整路径**。

**输出根目录**: `E:\output\需求标题_2024-12-23_15-30-00`
**主文件路径**: `E:\output\需求标题_2024-12-23_15-30-00\requirement_123_456.md`

---

### 📚 可读取文件路径汇总

**主需求文档**:
- `E:\output\需求标题_xxx\requirement_123_456.md`

**关联石墨文档**:
- `E:\output\需求标题_xxx\odocs\技术方案\技术方案.md`

**图片文件**:
- `E:\output\需求标题_xxx\images\req_123_456_0.png`

`read_devops_bug`

读取研发云Bug缺陷单信息，返回Markdown格式。支持获取Bug详情、评论和附件，并可自动下载图片和解压附件。

参数:

| 参数名 | 类型 | 必需 | 默认值 | 说明 | | ----------------- | ------- | ---- | -------- | -------------------------------- | | url | string | ✅ | - | 研发云Bug链接 | | saveImages | boolean | ❌ | true | 是否下载Bug详情和评论中的图片 | | saveAttachments | boolean | ❌ | true | 是否下载Bug中的附件 | | includeComments | boolean | ❌ | true | 是否包含Bug评论 | | autoExtract | boolean | ❌ | true | 是否自动解压压缩包附件 | | outputDir | string | ❌ | 配置目录 | 自定义输出目录路径 |

返回内容:

Bug基本信息（ID、标题、状态、优先级等）
Bug详情 HTML 内容
Bug评论列表
附件列表及本地路径
下载的图片路径列表

输出目录结构:

Bug标题_时间/
├── bug_projectId_bugId.md      # 主Bug文件
├── images/                     # Bug详情和评论中的图片
│   ├── bug_xxx_0.png
│   └── ...
└── attachments/                # 附件文件
    ├── 附件1.zip
    └── 附件1/                  # 解压后的文件夹

示例:

// 基本Bug读取
await read_devops_bug({ 
  url: "https://oneteam.myoas.com/micro-app/noah-coteam/bugList/list?projectId=123&projectType=1&bugId=456" 
})

// 完整读取（自定义选项）
await read_devops_bug({ 
  url: "https://oneteam.myoas.com/micro-app/noah-coteam/bugList/list?projectId=123&projectType=1&bugId=456",
  saveImages: true,
  saveAttachments: true,
  autoExtract: true
})

系统管理

`get_config`

查看当前 MCP 服务器的配置信息

`check_status`

检查 MCP 服务器运行状态和连接情况

🔐 安全与隐私

数据安全

所有网络通信均采用 HTTPS 加密
SSO Token 和 Cookie 信息经过脱敏处理
支持凭证自动过期和智能刷新机制
本地缓存文件采用安全存储方式

凭证管理

用户凭证安全存储在 ~/.odocs-mcp/credentials.json
凭证文件包含敏感的认证信息
⚠️ 重要：请勿将凭证文件分享或提交到代码仓库

权限控制

严格遵循企业 SSO 权限策略
仅能访问用户有权限的文档
自动处理权限过期和重新认证

🛠️ 开发与调试

本地开发

# 克隆项目
git clone https://github.com/yourusername/odocs-mcp.git
cd odocs-mcp

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建项目
npm run build

环境要求

Node.js >= 18.0.0
npm >= 8.0.0
支持 MCP 协议的 AI 客户端（如 Cursor、Claude Desktop）

调试技巧

# 检查 MCP 服务器连接
npm run inspect

# 查看详细日志
DEBUG=odocs-mcp* npm start

# 测试工具调用
npx odocs-mcp test-tools

📁 项目架构

odocs-mcp/
├── src/                         # TypeScript源代码
│   ├── auth/                    # SSO认证模块
│   │   ├── ssoAuth.ts           # SSO认证管理
│   │   └── credentialStore.ts   # 凭证存储管理
│   ├── odocs/                   # 石墨文档客户端
│   │   ├── client.ts            # 文档API客户端
│   │   ├── headerManager.ts     # 请求头管理
│   │   └── imageProcessor.ts    # 图片处理器
│   ├── devops/                  # 研发云客户端
│   │   ├── devopsClient.ts      # 研发云API客户端
│   │   └── devopsHeaderManager.ts # 请求头管理
│   ├── tools/                   # MCP工具实现
│   │   ├── readDoc.ts           # 石墨文档读取工具
│   │   └── readRequirement.ts   # 研发云需求读取工具
│   ├── utils/                   # 工具函数
│   ├── config.ts                # 配置管理
│   ├── types.ts                 # 类型定义
│   └── server.ts                # MCP服务器入口
├── dist/                        # 编译输出目录
├── env.example                  # 环境变量配置示例
└── package.json                 # 项目依赖配置

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

Fork 本项目到您的 GitHub 账户
创建特性分支 git checkout -b feature/amazing-feature
提交更改 git commit -m 'Add amazing feature'
推送分支 git push origin feature/amazing-feature
创建 Pull Request 并描述您的更改

代码规范

使用 TypeScript 进行开发
遵循 ESLint 和 Prettier 配置
添加适当的单元测试
更新相关文档

📄 开源协议

本项目采用 MIT License 开源协议。

🔗 参考资源

AI-Test Hub（核心参考）: https://oneteam.myoas.com/micro-app/ocode-na/InnerSource/testing/llm-extension.git/LICENSE/overview 本项目的架构设计、工具集成模式和最佳实践均参考该企业 AI 工具集成框架
Model Context Protocol 官方文档
MCP TypeScript SDK
Cursor IDE 官方文档

📞 获取帮助

遇到问题时，请按以下顺序寻求帮助：

📖 查阅本 README 文档和 API 参考
🔍 搜索已知问题
💬 提交新的 Issue，请提供：
- 详细的问题描述
- 复现步骤
- 环境信息（Node.js 版本、操作系统等）
- 相关的错误日志

⭐ 喜欢这个项目？请给我们一个 Star！ 您的支持是我们持续改进的动力。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🚀 odocs-mcp

📖 简介

✨ 核心特性

📦 安装与使用

在 Cursor 中配置

🎯 使用示例

在 AI 对话中调用 MCP 工具

登录认证

读取文档内容

带图片的文档读取

读取研发云需求

读取需求并分析关联文档

读取研发云Bug

检查系统状态

环境变量配置

Cursor配置env

配置说明

石墨文档配置

通用配置

研发云配置

🔧 MCP 工具 API 参考

认证相关

sso_login

sso_logout

文档操作

read_odocs

read_devops_requirement

read_devops_bug

系统管理

get_config

check_status

🔐 安全与隐私

数据安全

凭证管理

权限控制

🛠️ 开发与调试

本地开发

环境要求

调试技巧

📁 项目架构

🤝 贡献指南

代码规范

📄 开源协议

🔗 参考资源

📞 获取帮助

`sso_login`

`sso_logout`

`read_odocs`

`read_devops_requirement`

`read_devops_bug`

`get_config`

`check_status`