Theneo MCP Server

Theneo MCP 服务器

Theneo SDK的模型上下文协议服务器 人工智能时代API文档的自动化支柱。

 ](https://nodejs.org/) 

这个MCP服务器暴露了 Theneo的 API文档平台通过 模型上下文协议，允许AI助手自动创建、更新和发布API文档。

概述

Theneo MCP使任何AI助手（如Claude Desktop、VS Code Copilot、Cursor等）能够与Theneo的SDK进行交互，从而实现API文档的创建和维护的完全自动化。非常适合CI/CD流水线、AI驱动的工作流和开发者生产力工具。

主要特点

• 💬 自然语言只需交谈——无需记忆工具名称或参数！
• 🎯（目标） 基于名称的引用通过名称而非ID引用项目和工作区——AI会自动查找它们！
• 🤖 表示机器人。 “AI-First”翻译成中文是“人工智能优先”与任何兼容MCP的人工智能助手（Claude、VS Code、Cursor）配合使用
• 🔐 企业安全多源配置，操作系统密钥链支持，秘密掩码
• 🛠️（工具或修理的象征，无直接对应中文翻译，可理解为“工具”或“修理”等意象） 15款强大工具完整的项目生命周期管理——工作区、项目、版本、导出等
• 📦（包裹/箱子） 灵活输入支持OpenAPI/Swagger文件、URL、原始文本以及Postman集合
• 🚀 表情符号“🚀”在中文中通常直接以原样使用，不翻译，它表示火箭、发射或快速前进等意思。所以，这个表情符号在中文语境中就是“🚀”。 由人工智能驱动内置AI描述生成功能（填充、覆盖或跳过）
• 🔄 翻译为中文是：循环/旋转（符号本身无直接对应中文词汇，根据其含义可译为“循环”或“旋转”） 智能进口合并、覆盖或仅端点更新策略
• 地球🌍 配置文件支持管理多个环境（开发、测试、生产）

设计选择

为什么选择SDK而不是CLI？

直接SDK集成提供了类型安全性、更好的错误处理以及无需处理shell转义问题即可访问完整的API接口。

为什么选择OS Keychain？

无需环境变量或明文文件，即可安全存储静态凭证。通过keytar实现跨平台支持。

为何支持个人资料功能？

多环境工作流（开发/预生产/生产）很常见。配置文件使得在不同环境之间轻松切换上下文，无需管理繁琐的凭据。

为什么选择MCP协议？

MCP实现了AI工具集成的标准化。一次编写，即可在Claude、VS Code Copilot、Cursor以及未来的AI助手上运行。

安装

npm（推荐）

# Global installation
npm install -g theneo-mcp

# Verify installation
theneo-mcp --version

Homebrew（适用于 macOS/Linux）

# Add tap
brew tap theneo/theneo-mcp

# Install
brew install theneo-mcp

# Verify installation
theneo-mcp --version

Docker（注：Docker是一个用于开发、交付和运行应用程序的开源平台，可以实现应用容器化，简化应用部署过程。）

# Pull from Docker Hub
docker pull theneo/theneo-mcp:latest

# Run with API key
docker run -it --rm \
  -e THENEO_API_KEY=your_api_key \
  theneo/theneo-mcp:latest

见 关于详细的Docker使用方法。

本地开发

git clone https://github.com/atombreak/theneo-mcp.git
cd theneo-mcp
npm install
npm run build

快速入门（5分钟）

获取您的API密钥

访问 https://app.theneo.io/（该网址直接翻译为中文保持原样，因为网址本身不是语言内容，无需翻译其含义，只是说明这是一个网址链接） 获取您的Theneo API密钥。

2. 配置身份验证

选项A：OS密钥链（推荐用于本地开发）

theneo-mcp creds save --profile default --apiKey YOUR_API_KEY

选项B：环境变量

export THENEO_API_KEY=YOUR_API_KEY

3. 连接您的AI助手

Claude Desktop（可译为“Claude桌面版”或保持原样，若“Desktop”在此处特指某种平台或版本，则可根据具体语境翻译）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "theneo": {
      "command": "theneo-mcp",
      "args": ["server"]
    }
  }
}

VS Code Copilot（VS代码协作者/VS代码同伴，通常简称为“VS Code 的 Copilot”）

添加到你的VS Code settings.json：

{
  "chat.mcp.access": "all",
  "chat.mcp.servers": {
    "theneo": {
      "command": "theneo-mcp",
      "args": ["server"],
      "env": {
        "THENEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

光标

添加到光标设置（设置 → MCP）：

{
  "mcpServers": {
    "theneo": {
      "command": "theneo-mcp",
      "args": ["server", "--profile", "default"]
    }
  }
}

4. 进行测试

在你的AI助手中，只需自然对话：

Show me my Theneo workspaces

然后创建一个项目：

Create a new project called "Demo API" using the Petstore OpenAPI example 
from GitHub. Make it public and enable AI descriptions.

或者，如果你更倾向于明确表达：

Use theneo_create_project with name "Demo API", 
link "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json",
publish true, isPublic true, and descriptionGeneration "FILL"

💡 灯泡（或表示“灵感”、“想法”的符号） 专业小贴士你无需记忆工具名称或参数——只需用简单的英语描述你的需求即可！

配置

配置源与优先级

配置从多个来源加载，且具有明确的优先级（从高到低排列）：

环境变量

项目配置文件

创建 .theneo-mcp.yaml 或者 .theneo-mcp.json 在你的项目根目录中：

# .theneo-mcp.yaml
profile: default
baseApiUrl: https://api.theneo.io
baseAppUrl: https://app.theneo.io

# Multi-environment support
profiles:
  development:
    profile: development
  
  production:
    profile: production

⚠️ 安全提示永远不要将API密钥提交到版本控制系统中！请将它们存储在密钥链或环境变量中。

用户配置

创建 ~/.config/theneo-mcp/config.json (Linux/macOS) 或 %AppData%/theneo-mcp/config.json （Windows）：

{
  "profile": "default",
  "baseApiUrl": "https://api.theneo.io",
  "baseAppUrl": "https://app.theneo.io",
  "profiles": {
    "default": {},
    "production": {}
  }
}

OS 密钥链（推荐）

在您的系统密钥链中安全存储API密钥：

# Save API key
theneo-mcp creds save --profile default --apiKey YOUR_KEY

# Remove API key
theneo-mcp creds rm --profile default

# List stored profiles
theneo-mcp creds list

使用配置文件

轻松切换环境：

# Use production profile
theneo-mcp server --profile production

# Or via environment
THENEO_PROFILE=production theneo-mcp server

可用工具

💡 灯泡（或“想法”、“灵感”等，根据上下文可灵活翻译） 提示你不需要使用确切的工具名称！只需自然地与你的AI助手交谈，它就会自动判断出应该调用哪个工具。

🎯（目标） 新现在你可以参考 项目 并且 工作区 由 名字 无需记住他们的ID！人工智能会自动为您查找。

1. theneo_list_workspaces

列出您账户可访问的所有工作区。

参数： 无

自然语言示例：

Show me my Theneo workspaces

What workspaces do I have access to?

List all my Theneo workspaces

显式工具调用（用于测试/调试）：

Use theneo_list_workspaces

2. theneo_list_projects

列出工作区中的所有项目或跨所有工作区列出项目。您可以使用ID、密钥（slug）或名称按工作区进行过滤。返回项目名称、ID和详细信息。

参数：

• workspaceId (字符串，可选)：用于过滤项目的Workspace ID
• workspaceKey (字符串，可选)：用于过滤项目的工区密钥/标识符
• workspaceName (字符串，可选)：用于过滤项目的工区名称

自然语言示例：

Show me all my projects

List all projects in the "Engineering" workspace

What projects do I have in my "Production" workspace?

显式工具调用（用于测试/调试）：

Use theneo_list_projects

3. theneo_create_project

创建一个带有可选规范导入和AI生成功能的新API文档项目。您可以按ID、密钥（slug）或名称指定工作区。

参数：

• name （字符串，必填）：项目名称
• workspaceKey (字符串，可选)：工作区代号
• workspaceId （字符串，可选）：工作区ID
• workspaceName (字符串，可选)：工作区名称
• publish （布尔值，可选）：立即发布
• isPublic (布尔值，可选)：使项目公开
• descriptionGeneration (枚举，可选)： FILL | OVERWRITE | NO_GENERATION
• 数据来源 （选择一个）：

- file (字符串)：本地OpenAPI/Swagger文件的路径 - link (字符串)：OpenAPI/Swagger 规范的 URL - text (字符串): 原始 OpenAPI/Swagger 规范 - postmanApiKey + postmanCollectionIds从Postman导入

自然语言示例：

Create a new project called "Payment API" in the "Engineering" workspace from 
this OpenAPI spec: https://example.com/openapi.json and make it public with AI descriptions

I need to create API documentation for my REST API in my "Production" workspace. 
The spec is at ./specs/api.yaml. Name it "User Service API" and enable AI descriptions.

Can you create a Theneo project named "Stripe Clone" in the "Public APIs" workspace 
using the Petstore example from GitHub? Make it public and publish it immediately.

显式工具调用（用于测试/调试）：

Use theneo_create_project with:
- name: "My API"
- link: "https://example.com/openapi.json"
- publish: true
- isPublic: true
- descriptionGeneration: "FILL"

示例回复：

{
  "projectId": "proj_abc123xyz",
  "publishData": {
    "projectKey": "my-api",
    "companySlug": "acme-corp",
    "publishedPageUrl": "https://app.theneo.io/acme-corp/my-api",
    "baseUrlRequired": false
  }
}

4. theneo_import_project_document

在现有项目中导入或更新API文档。 你可以通过名称而不是ID来引用项目和工作区。

参数：

• projectId （字符串，可选）：目标项目ID
• projectName (字符串，可选)：目标项目名称（可作为projectId的替代）
• workspaceId （字符串，可选）：工作区ID（在使用projectName时很有帮助）
• workspaceKey (字符串，可选)：工作区密钥/别名（在使用 projectName 时很有帮助）
• workspaceName (字符串，可选)：工作区名称（在使用 projectName 时很有帮助）
• publish (布尔值，可选)：导入后发布
• importOption （枚举，可选）： MERGE | OVERWRITE | ENDPOINTS_ONLY
• 数据来源 （与create_project相同，一个必需）

自然语言示例：

Update the "Payment API" project in my "Engineering" workspace with the latest 
spec from ./api/openapi.yaml and merge it with existing content

I need to import a new version into the "User Service" project in the "Production" 
workspace. Use this URL: https://api.example.com/openapi.json and overwrite everything.

Import the updated Postman collection into "My Company API" in the "Public APIs" 
workspace and publish it with merge.

明确的工具调用（用于测试/调试）：

Use theneo_import_project_document with:
- projectId: "proj_123"
- file: "./openapi.json"
- importOption: "MERGE"
- publish: true

5. theneo_publish_project

发布一个项目以使其上线运行。 你可以通过名称来引用项目和工作区可选地指定要发布的版本。

参数：

• projectId (字符串，可选)：项目ID
• projectName （字符串，可选）：项目名称（可作为projectId的替代）
• workspaceId (字符串，可选)：工作区ID（在使用projectName时有所帮助）
• workspaceKey （字符串，可选）：工作区密钥/标识符（在使用 projectName 时很有帮助）
• workspaceName （字符串，可选）：工作区名称（在使用 projectName 时很有帮助）
• versionId (字符串，可选)：要发布的版本ID（如果未指定，则发布默认版本）

自然语言示例：

Publish the "Payment API" project in my "Engineering" workspace

Make the "User Service API" in the "Production" workspace live

Publish the project called "Stripe Clone" in "Public APIs"

显式工具调用（用于测试/调试）：

Use theneo_publish_project with projectId "proj_123"

6. theneo_preview_link

获取项目的编辑器预览URL。 你可以通过名称来引用项目和工作区。

参数：

• projectId (字符串，可选)：项目ID
• projectName （字符串，可选）：项目名称（可作为projectId的替代）
• workspaceId （字符串，可选）：工作区ID（在使用projectName时很有帮助）
• workspaceKey （字符串，可选）：工作区密钥/标识符（在使用 projectName 时很有帮助）
• workspaceName （字符串，可选）：工作区名称（在使用 projectName 时有所帮助）

自然语言示例：

Get me the preview link for "Payment API" in the "Engineering" workspace

Show me where I can edit the "User Service" project in "Production"

What's the URL to view "My Company API" in the "Public APIs" workspace?

显式工具调用（用于测试/调试）：

Use theneo_preview_link for project "proj_123"

7. theneo_wait_for_generation

等待AI描述生成完成。 你可以通过名称来引用项目和工作区。

参数：

• projectId （字符串，可选）：项目ID
• projectName （字符串，可选）：项目名称（可作为 projectId 的替代）
• workspaceId （字符串，可选）：工作区ID（在使用projectName时很有帮助）
• workspaceKey (字符串，可选)：工作区密钥/别名（在使用 projectName 时很有帮助）
• workspaceName (字符串，可选)：工作区名称（在使用 projectName 时很有帮助）
• retryTimeMs （数字，可选）：轮询间隔（默认：2500）
• maxWaitTimeMs （数字，可选）：最长等待时间（默认：120000）

自然语言示例：

Wait for the AI to finish generating descriptions for "Payment API" in "Engineering"

Check if AI generation is complete for "User Service" in the "Production" workspace

Keep checking until the AI descriptions are done for "My Company API" in "Public APIs"

明确的工具调用（用于测试/调试）：

Use theneo_wait_for_generation for project "proj_123"

8. theneo_get_generation_status

获取项目中AI描述生成的当前状态和进度。 你可以通过名称来引用项目和工作区。

参数：

• projectId (字符串，可选)：项目ID
• projectName （字符串，可选）：项目名称（可替代 projectId）
• workspaceId （字符串，可选）：工作区ID（在使用projectName时很有帮助）
• workspaceKey (字符串，可选)：工作区密钥/标识符（在使用 projectName 时很有帮助）
• workspaceName (字符串，可选)：工作区名称（在使用 projectName 时很有帮助）

自然语言示例：

Check the AI generation status for "Payment API" in "Engineering"

What's the progress of AI description generation for "User Service"?

Show me the generation status of "My Company API" in the "Public APIs" workspace

显式工具调用（用于测试/调试）：

Use theneo_get_generation_status with projectId "proj_123"

9. theneo_delete_project

永久删除一个项目。 你可以通过名称来引用项目和工作区⚠️ 此操作无法撤销。

参数：

• projectId （字符串，可选）：项目ID
• projectName （字符串，可选）：项目名称（可替代projectId）
• workspaceId (字符串，可选)：工作区ID（在使用projectName时很有帮助）
• workspaceKey (字符串，可选)：工作区密钥/别名（在使用 projectName 时很有帮助）
• workspaceName (字符串，可选)：工作区名称（在使用 projectName 时很有帮助）

自然语言示例：

Delete the "Old API" project from my "Engineering" workspace

I need to remove the "Test Project" from the "Staging" workspace

Can you delete "Legacy API v1" in my "Production" workspace?

显式工具调用（用于测试/调试）：

Use theneo_delete_project with projectId "proj_123"

10. theneo_list_project_versions

列出特定项目的所有版本。 你可以通过名称来引用项目和工作区。

参数：

• projectId （字符串，可选）：项目ID
• projectName (字符串，可选)：项目名称（可替代projectId）
• workspaceId （字符串，可选）：工作区ID（在使用projectName时很有帮助）
• workspaceKey （字符串，可选）：工作区密钥/标识符（在使用 projectName 时很有帮助）
• workspaceName (字符串，可选)：工作区名称（在使用 projectName 时很有帮助）

自然语言示例：

Show me all versions of the "Payment API" project in "Engineering"

List versions for "User Service" in the "Production" workspace

What versions does the "My Company API" have?

明确的工具调用（用于测试/调试）：

Use theneo_list_project_versions with projectId "proj_123"

11. theneo_create_project_version

创建项目的新版本。 你可以通过名称来引用项目和工作区.

参数：

• name (字符串，必填): 版本名称
• projectId (字符串，可选)：项目ID
• projectName (字符串，可选)：项目名称（可作为projectId的替代）
• workspaceId (字符串，可选)：工作区ID（在使用projectName时很有帮助）
• workspaceKey （字符串，可选）：工作区密钥/别名（在使用 projectName 时很有帮助）
• workspaceName （字符串，可选）：工作区名称（在使用 projectName 时很有帮助）
• previousVersionId （字符串，可选）：要复制的先前版本ID
• isNewVersion (布尔值，可选)：是否为新版本
• isEmpty (布尔值，可选)：版本是否应为空
• isDefault (布尔值，可选)：是否应将其设为默认版本

自然语言示例：

Create a new version "v2.0" for "Payment API" in the "Engineering" workspace

Add version "2024-Q1" to the "User Service" project in "Production"

Create an empty version called "v3.0-beta" for "My Company API"

显式工具调用（用于测试/调试）：

Use theneo_create_project_version with:
- name: "v2.0"
- projectId: "proj_123"

12. theneo_delete_project_version

删除项目的特定版本。⚠️ 此操作无法撤销。

参数：

• versionId （字符串，必填）：要删除的版本ID

自然语言示例：

Delete version "ver_abc123" from the project

Remove the beta version with ID ver_xyz789

I need to delete version ver_old456

显式工具调用（用于测试/调试）：

Use theneo_delete_project_version with versionId "ver_123"

13. theneo_add_subscriber_to_version

添加一个电子邮件订阅者以接收特定项目版本的更新。

参数：

• email （字符串，必填）：用于订阅的电子邮件地址
• projectVersionId （字符串，必填）：项目版本ID

自然语言示例：

Add john@company.com as a subscriber to version ver_abc123

Subscribe jane.doe@example.com to receive updates for version ver_xyz789

I want to add team@company.com to the subscriber list for version ver_def456

显式工具调用（用于测试/调试）：

Use theneo_add_subscriber_to_version with:
- email: "user@example.com"
- projectVersionId: "ver_123"

14. theneo_export_project

导出项目的文档。 你可以通过名称来引用项目和工作区。

参数：

• projectId (字符串，可选)：项目ID
• projectName (字符串，可选)：项目名称（可替代projectId）
• workspaceId (字符串，可选)：工作区ID（在使用projectName时很有帮助）
• workspaceKey （字符串，可选）：工作区密钥/别名（在使用 projectName 时很有帮助）
• workspaceName (字符串，可选)：工作区名称（在使用 projectName 时有所帮助）
• versionId （字符串，可选）：要导出的版本ID
• dir （字符串，可选）：保存导出文件的目录
• noGeneration （布尔值，可选）：跳过AI生成
• shouldGetPublicViewData (布尔值，可选)：获取公共视图数据
• openapi (布尔值，可选)：以OpenAPI格式导出

自然语言示例：

Export the "Payment API" project from the "Engineering" workspace as OpenAPI

Download the documentation for "User Service" in "Production" to ./exports

Export "My Company API" with public view data

明确的工具调用（用于测试/调试）：

Use theneo_export_project with:
- projectId: "proj_123"
- openapi: true

15. theneo_list_postman_collections

列出可以使用提供的Postman API密钥访问的所有Postman集合。

参数：

• postmanApiKey Postman API密钥

自然语言示例：

Show me my Postman collections using this API key: pmak_xyz123

List all Postman collections I have access to

What Postman collections are available with my API key?

显式工具调用（用于测试/调试）：

Use theneo_list_postman_collections with postmanApiKey "pmak_xyz123"

演示脚本（端到端）

这个5分钟的演示展示了完整的流程。您可以使用任意一种 自然语言 或者 明确的工具调用。

🗣️ 自然语言版本（推荐）

只需自然地与您的AI助手交谈：

Step 1: Show me my Theneo workspaces

Step 2: Create a new project called "USPTO API Documentation" using this OpenAPI spec:
https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/uspto.json
Make it public, publish it immediately, and enable AI-generated descriptions to fill in missing content.

Step 3: Wait for the AI description generation to complete for that project

Step 4: Get me the preview link so I can view it in the editor

Step 5: Now update the project with the local file ./examples/sample-openapi.json
and merge it with the existing content, then publish it

Step 6: Finally, publish the project and show me the published URL

🔧 显式工具调用版本（用于测试）

如果您需要精确控制或正在进行调试：

Step 1: List workspaces
Use theneo_list_workspaces

Step 2: Create a project with AI generation
Use theneo_create_project with:
- name: "USPTO API Documentation"
- link: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/uspto.json"
- publish: true
- isPublic: true
- descriptionGeneration: "FILL"

Step 3: Wait for AI to finish
Use theneo_wait_for_generation with the project ID from step 2

Step 4: Get the preview link
Use theneo_preview_link with the project ID

Step 5: Import an update (merge mode)
Use theneo_import_project_document with:
- projectId: (from step 2)
- file: "./examples/sample-openapi.json"
- importOption: "MERGE"
- publish: true

Step 6: Get final published URL
Use theneo_publish_project with the project ID

💡 现实生活中的对话示例

You: "Hey, can you help me set up documentation for my API?"

AI: "Of course! Do you have an OpenAPI spec?"

You: "Yes, it's at https://api.mycompany.com/openapi.json"

AI: "Great! What would you like to name the project?"

You: "Call it 'MyCompany API v2' and make it public with AI descriptions"

AI: *[Creates project, waits for AI, shows preview link]*
"Done! Your documentation is live at [URL]. Would you like to make any changes?"

You: "Actually, I need to update the 'MyCompany API v2' project with a new spec"

AI: *[Automatically looks up project by name, imports new spec]*
"Updated! The changes have been merged and published."

🎯 使用名称代替ID（再也不用复制粘贴了！）

其中一个最强大的功能是能够引用 按名称查找项目和工作区：

# Old way (hard to remember)
"Create project in workspace ws_abc123 and publish project proj_xyz456"

# New way (natural)
"Create a project in my 'Engineering' workspace and publish the 'Payment API' project"

人工智能将自动：

1. 解析工作区名称 → 工作区ID（如需）
2. 解析项目名称 → 项目ID（如需要）
3. 执行操作
4. 返回一条友好的信息

这适用于：

• ✅ 工作区引用：ID、密钥（slug）或名称
• ✅ 项目参考：ID或名称
• ✅ 项目的所有操作：创建、导入、发布、预览、删除、导出
• ✅ 版本管理：列出、创建、删除版本
• ✅ AI生成：等待完成，检查状态
• ✅ 外部集成：列出Postman集合，添加订阅者

再也不用复制粘贴那些晦涩难懂的ID了！

更多示例在 examples/demo-prompts.md。

安全最佳实践

✅ 做

• 使用操作系统密钥链 本地机器上的API密钥
• 使用环境变量 在持续集成/持续交付（CI/CD）和容器技术中
• 启用密码掩码 在你的持续集成（CI）日志中
• 轮换API密钥 定期并在演示后（进行）
• 使用配置文件 隔离环境
• 评论 .gitignore 排除秘密
• 使用 .npmignore 防止泄露秘密

❌ 不要

• 永远不要承诺 API密钥到git
• 从不记录 完整的配置对象
• 永远不要使用 URL或查询参数中的API密钥
• 永远不要分享 公共频道中的API密钥
• 避免 将密钥存储在项目RC文件中并提交到git

CI/CD 集成

GitHub Actions 的工作流示例：

name: Update API Docs

on:
  push:
    paths:
      - 'openapi.yaml'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Theneo MCP
        run: npm install -g theneo-mcp
      
      - name: Update Documentation
        env:
          THENEO_API_KEY: ${{ secrets.THENEO_API_KEY }}
        run: |
          # Your automation script here
          # Call MCP tools via a script or AI assistant

持续集成（CI）的安全注意事项：

• 商店 THENEO_API_KEY 作为GitHub密钥
• 使用 secrets. 语法以避免暴露
• 如果Theneo支持OIDC，请考虑使用短期有效令牌
• 日志中的掩码秘密： echo "::add-mask::$THENEO_API_KEY"

发展

从源代码构建

git clone https://github.com/atombreak/theneo-mcp.git
cd theneo-mcp
npm install
npm run build

开发模式

npm run dev  # Start server with auto-reload

代码质量

npm run lint        # Run ESLint
npm run format      # Format with Prettier
npm run type-check  # TypeScript validation

项目结构

theneo-mcp/
├── src/
│   ├── server.ts       # MCP server implementation
│   ├── cli.ts          # CLI commands
│   ├── config.ts       # Configuration schema
│   ├── loadConfig.ts   # Multi-source config loader
│   ├── credentials.ts  # Keychain management
│   └── utils/
│       └── logger.ts   # Structured logging with secret masking
├── examples/           # Sample files and demos
├── dist/              # Compiled output
└── package.json

故障排除

API密钥未找到

问题： 服务器退出，提示“API密钥未配置”

解决方案：

1. 设置环境变量： export THENEO_API_KEY=your_key
2. 保存到钥匙串： theneo-mcp creds save --apiKey your_key
3. 检查个人资料： theneo-mcp server --profile default

钥匙串不可用

问题： “操作系统的钥匙串不可用”

解决方案： 请改用环境变量或配置文件：

export THENEO_API_KEY=your_key
theneo-mcp server

MCP服务器无法连接

问题： AI助手找不到工具

解决方案：

1. 配置更改后重启您的AI助手
2. 检查日志：查找MCP连接错误
3. 验证命令路径：使用绝对路径 theneo-mcp
4. 手动测试：运行 theneo-mcp server 查看启动日志

导入失败

问题： “无法导入文档”

解决方案：

1. 验证文件路径或URL是否可访问
2. 确保OpenAPI规范是有效的JSON/YAML格式
3. 检查项目ID是否正确
4. 审查API密钥权限

AI生成超时

问题： “生成失败或超时”

解决方案：

1. 增加超时时间： maxWaitTimeMs: 300000 （5分钟）
2. 检查Theneo仪表板以查看生成状态
3. 再试一次——大规格可能需要一些时间

发布到 npm

预发布检查清单

• \[ \] 更新版本中的 package.json
• \[ \] 运行 npm run type-check
• \[ \] 运行 npm run lint
• \[ \] 测试构建： npm run build
• \[ \] 验证 .npmignore 排除秘密
• \[ \] 测试安装： npm pack 并在本地安装
• \[ \] 更新 CHANGELOG.md 文件

发布

npm run prepublishOnly  # Runs checks and build
npm publish

什么会被发表

✅ 包括：

• 编译后的JavaScriptdist/）
• 包元数据（package.json)
• 文档（README.md， LICENSE）

❌（表示错误或否定） 被排除在外 （通过 .npmignore):

• TypeScript 源代码（src/)
• 测试文件和覆盖率（src/__tests__/， coverage/， *.test.ts)
• 环境文件（.env， .env.*)
• 包含潜在敏感信息的示例配置（.theneo-mcp.json， .theneo-mcp.yaml）
• 开发配置（tsconfig.json， vitest.config.ts， eslint.config.js)
• CI/CD 配置（.github/，GitHub Actions 工作流）
• Docker 文件（Dockerfile， .dockerignore)
• IDE 设置 (.vscode/， .idea/)

安全提示： 这个（或：那个） .npmignore 文件已配置为排除所有可能敏感的文件。发布前请务必检查：

# Preview what will be published
npm pack --dry-run

# Check for secrets in package
tar -tzf theneo-mcp-*.tgz | grep -E '\.(env|key|pem|crt)'

测试

这个项目具有全面的测试覆盖率，包括单元测试和集成测试。

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Open test UI
npm run test:ui

遥测

Theneo MCP 包括 可选的，以隐私为先的遥测技术 以帮助改进该工具。遥测是指：

• ✅ 选择加入（或：自愿注册） - 默认禁用
• ✅ 匿名 - 未收集任何个人数据
• ✅ 本地 - 存储在您机器上的数据
• ✅ 透明的 - 随时查看 theneo-mcp telemetry status

# Enable telemetry
theneo-mcp telemetry enable

# View what's collected
theneo-mcp telemetry status

# Disable anytime
theneo-mcp telemetry disable

持续集成/持续交付（CI/CD）

该项目包含了全面的GitHub Actions工作流：

• CI（企业识别系统/品牌标识）每次推送/拉取请求时，都在 Node 18、20、22 上运行测试
• 发布自动在npm上发布并在版本标签时更新Homebrew
• 质量每周进行安全审计和依赖项检查

见 用于查看工作流程详情。

做出贡献

欢迎投稿！请：

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支
3. 为新功能编写测试
4. 确保所有检查均通过： npm test
5. 提交一个拉取请求

看见 CONTRIBUTING.md 翻译为中文是：“贡献指南.md” 或 “如何贡献.md”（具体翻译可能根据上下文略有调整，但核心意思是关于如何为项目做贡献的指南文件）。在这里，\.md\ 表示这是一个 Markdown 格式的文件 以获取详细指南。

许可证

MIT 许可证 - 详见 许可证 文件详情请见附件

链接

• Theneo平台: https://theneo.io（该网址可直接作为翻译结果，因为网址本身无需翻译，但若要说明其含义，可表述为“Theneo的官方网站”或具体根据该网站内容进行描述，不过在此直接给出网址形式的翻译更为常见。）
• Theneo SDK（软件开发工具包）：
• 模型上下文协议： https://modelcontextprotocol.io（该网址可翻译为“模型上下文协议网站”，但实际翻译时通常保留原网址不变，因为网址本身是一种标识，直接使用即可）
• 问题：

支持

• 文档这个README文件以及 examples/demo-prompts.md
• 问题：
• Theneo 支持: https://theneo.io/support 翻译为中文是：“https://theneo.io/支持页面” 或 “https://theneo.io/帮助中心”

______________________________________________________________________

用心打造，迎接AI赋能的文档新时代

*将Theneo定位为开发者文档的自动化核心工具*