数据源

数据源配置指南

本指南介绍如何在 Tentarc 中配置数据源（MCP 服务器、API、本地文件系统）。

数据源设置流程

当用户想要添加新数据源时，请遵循此对话式设置流程，创建量身定制、文档完善的集成。

0. 搜索专用数据源指南（必需的第一步）

在执行任何操作之前，使用 tentarc-agents-docs MCP 搜索专用指南：

mcp__tentarc-docs__SearchTentarcAgents({ query: "{服务} source setup" })

可用指南： GitHub、Linear、Slack、Gmail、Google Calendar、Google Drive、Google Docs、Google Sheets、Outlook、Microsoft Calendar、Teams、SharePoint、Craft、Filesystem、Brave Search、Memory

如果存在该服务的指南：

仔细阅读指南内容
特别注意"Setup Hints"部分 - 包含关键说明
遵循任何 CRITICAL/MANDATORY 指令（例如，GitHub 需要先检查 gh CLI）
始终通过 WebSearch 验证当前 API 端点 - URL 经常变化

为什么这很重要： 某些服务有必须在创建数据源之前检查的重要前提条件或注意事项。跳过此步骤可能导致设置失败或配置冗余。

1. 理解用户意图

在创建任何配置之前，询问以了解：

主要目的：他们想通过这个数据源实现什么？
范围：要关注的特定项目、团队、仓库或数据？
常见任务：他们最常执行的操作是什么？
访问级别：只读探索还是完全访问？

示例问题：

"我很乐意帮您设置 Linear！几个问题：

您主要用 Linear 做什么？（问题跟踪、冲刺计划等）

有特定的团队或项目要关注吗？

应该设置为只读探索还是完全访问？"

2. 研究服务

使用可用工具了解服务：

WebSearch：查找官方文档、API 参考、最佳实践
查找：速率限制、配额、认证方法
识别：与用户目标相关的关键端点或工具
注意：任何需要记录的限制或注意事项

3. 智能配置

根据研究和用户意图，创建包含所有必需字段的 config.json：

必需字段：

id - 必需：唯一标识符字符串。格式：{slug}_{random}（例如 linear_a1b2c3d4）。使用任何方法生成随机部分（例如 8 个十六进制字符）。
name、slug、provider、type - 基本标识
icon - 必需：服务的 favicon、logo 或应用图标的 URL。搜索网络找到看起来像应用图标的合适图标。图标会自动下载并本地缓存。使用 emoji 作为后备。
tagline - 必需：Agent 上下文的简短描述（例如"问题跟踪、冲刺计划和项目管理"）
类型特定配置（mcp、api 或 local）
适合服务的认证方法

4. 配置探索模式权限（必需）

数据源默认应在探索模式下工作。创建 permissions.json 以允许只读操作。

工作原理： 数据源 permissions.json 中的模式会自动限定到该数据源。编写简单模式如 list - 系统会在内部将其转换为 mcp__<sourceSlug>__.*list。这可以防止跨数据源泄漏。

对于 MCP 数据源：

连接后，列出服务器的可用工具
识别只读工具（list、get、search、find、query 操作）
为这些操作创建简单模式

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "所有列表操作" },
    { "pattern": "get", "comment": "所有获取/读取操作" },
    { "pattern": "search", "comment": "所有搜索操作" },
    { "pattern": "find", "comment": "所有查找操作" }
  ]
}

对于 API 数据源：

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "所有 GET 请求都是只读的" },
    { "method": "POST", "path": "^/search", "comment": "搜索端点（虽然是 POST 但只读）" }
  ]
}

对于本地数据源：

{
  "allowedBashPatterns": [
    { "pattern": "^(ls|cat|head|tail|grep|find|tree)\\s", "comment": "只读命令" }
  ]
}

目标： 数据源应在探索模式下完全可用。默认允许所有读取操作。只阻止实际的修改操作（create、update、delete）。

5. 编写全面的 guide.md

创建针对用户上下文的 guide.md：

总结数据源在其特定用例中的用途
记录与其工作流相关的功能
包含他们提到的特定项目/团队/范围引用
添加针对其任务的使用示例
注明速率限制、配额或限制

6. 测试和验证（强制）

创建任何数据源后必须使用 source_test 工具。 这适用于所有数据源类型 - MCP、API 和本地文件系统数据源。这不是可选的。

mcp__session__source_test({ sourceSlug: "{slug}" })

source_test 工具：

根据 schema 验证 config.json
如果提供了 URL 则下载并缓存图标
测试连接以验证数据源可访问
报告缺失字段（icon、tagline）应该添加

验证通过后，触发相应的认证流程：

OAuth 数据源：source_oauth_trigger({ sourceSlug: "{slug}" })
Bearer/API key：source_credential_prompt({ sourceSlug: "{slug}", mode: "bearer" })
Google 服务：source_google_oauth_trigger({ sourceSlug: "{slug}" })
Microsoft 服务：source_microsoft_oauth_trigger({ sourceSlug: "{slug}" })
Slack：source_slack_oauth_trigger({ sourceSlug: "{slug}" })

不要跳过验证 - 它在运行时失败之前捕获配置错误。

guide.md 最佳实践

guide.md 文件至关重要——它帮助 Claude 了解如何在未来的会话中有效使用数据源。

结构

# 数据源名称

数据源提供什么以及用户特定用例的简要描述。

## 范围

此数据源提供的数据/功能。包括：
- 用户提到的特定项目、团队或仓库
- 相关过滤器或默认值
- 任何访问限制

## 指南

- 使用此数据源的最佳实践
- 需要注意的速率限制或配额
- 用户需要的常见模式
- 需要避免或小心的事项

## 示例

针对用户工作流的具体示例：
- "要查找 Craft iOS 项目中的问题：..."
- "要搜索移动团队的最近提交：..."

关键原则

针对用户上下文具体化：引用他们提到的项目、团队和任务
包含具体示例：使用他们实际的项目名称和工作流
记录用户偏好：他们分享的任何偏好供未来会话使用
注明范围边界：数据源能做什么和不能做什么
保持可操作性：专注于 Claude 需要知道的内容以有效提供帮助

概述

数据源存储为以下路径的文件夹：

~/.tentarc/workspaces/{workspaceId}/sources/{sourceSlug}/

每个数据源文件夹包含：

config.json - 数据源配置（必需）
guide.md - Claude 的使用文档（可选）
permissions.json - 探索模式的自定义权限规则（可选）
icon.svg、icon.png、icon.jpg 或 icon.jpeg - 数据源图标（可选）

config.json Schema

{
  "id": "linear_a1b2c3d4",        // 唯一标识符：{slug}_{random}
  "name": "人类可读名称",
  "slug": "url-safe-identifier",
  "enabled": true,
  "provider": "provider-name",
  "type": "mcp" | "api" | "local",

  // 必需：UI 和 agent 上下文的图标和标语
  "icon": "https://example.com/favicon.ico",  // URL（自动下载）或 emoji
  "tagline": "Agent 上下文的简短描述",

  // MCP 数据源：
  "mcp": {
    "url": "https://mcp.example.com",
    "authType": "oauth" | "bearer" | "none"
  },

  // API 数据源：
  "api": {
    "baseUrl": "https://api.example.com/",  // 必须有尾部斜杠
    "authType": "bearer" | "header" | "query" | "basic" | "none",
    "headerName": "X-API-Key",      // header 认证用
    "queryParam": "api_key",         // query 认证用
    "authScheme": "Bearer"           // bearer 认证用（默认："Bearer"）
  },

  // 本地数据源：
  "local": {
    "path": "/path/to/folder"
  },

  // 状态（由 source_test 更新）：
  "isAuthenticated": true,
  "connectionStatus": "connected" | "needs_auth" | "failed" | "untested",
  "lastTestedAt": 1704067200000,

  // 时间戳：
  "createdAt": 1704067200000,
  "updatedAt": 1704067200000
}

数据源类型

MCP 数据源

Model Context Protocol 服务器通过 HTTP/SSE 提供工具。

OAuth 认证（推荐）：

{
  "id": "linear_a1b2c3d4",
  "type": "mcp",
  "provider": "linear",
  "mcp": {
    "url": "https://mcp.linear.app",
    "authType": "oauth"
  }
}

创建后，使用 source_oauth_trigger 进行认证。

Bearer token 认证：

{
  "type": "mcp",
  "provider": "custom-mcp",
  "mcp": {
    "url": "https://my-mcp-server.com",
    "authType": "bearer"
  }
}

创建后，使用 source_credential_prompt 并设置 mode 为 "bearer"。

公开（无认证）：

{
  "type": "mcp",
  "provider": "public-mcp",
  "mcp": {
    "url": "https://public-mcp.example.com",
    "authType": "none"
  }
}

Stdio 传输（本地命令）：

对于通过命令行（npx、node、python）本地运行的 MCP 服务器，使用 stdio 传输。

用户经常提供 Claude Desktop / Claude Code 格式的配置：

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb"]
    }
  }
}

转换为原生格式：

{
  "type": "mcp",
  "name": "Airbnb",
  "provider": "airbnb",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@openbnb/mcp-server-airbnb"],
    "authType": "none"
  }
}

带环境变量：

{
  "type": "mcp",
  "name": "Brave Search",
  "provider": "brave",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "your-api-key"
    },
    "authType": "none"
  }
}

API 数据源

REST API 成为 Claude 可以调用的灵活工具。

重要： 需要认证的 API 数据源需要 testEndpoint 来在 source_test 期间验证凭据。没有它，我们无法验证您的凭据是否有效。

Header 认证（X-API-Key 风格）：

{
  "type": "api",
  "provider": "exa",
  "api": {
    "baseUrl": "https://api.exa.ai/",
    "authType": "header",
    "headerName": "x-api-key",
    "testEndpoint": {
      "method": "POST",
      "path": "search",
      "body": { "query": "test", "numResults": 1 }
    }
  }
}

Bearer token（Authorization header）：

{
  "type": "api",
  "provider": "openai",
  "api": {
    "baseUrl": "https://api.openai.com/v1/",
    "authType": "bearer",
    "testEndpoint": {
      "method": "GET",
      "path": "models"
    }
  }
}

Query 参数：

{
  "type": "api",
  "provider": "weather",
  "api": {
    "baseUrl": "https://api.weather.com/",
    "authType": "query",
    "queryParam": "apikey",
    "testEndpoint": {
      "method": "GET",
      "path": "v1/current"
    }
  }
}

Basic 认证：

{
  "type": "api",
  "provider": "jira",
  "api": {
    "baseUrl": "https://your-domain.atlassian.net/rest/api/3/",
    "authType": "basic",
    "testEndpoint": {
      "method": "GET",
      "path": "myself"
    }
  }
}

testEndpoint 配置

testEndpoint 指定验证凭据时调用的端点：

{
  "testEndpoint": {
    "method": "GET",           // "GET" 或 "POST"
    "path": "v1/me",           // 相对于 baseUrl 的路径（无前导斜杠）
    "body": { ... }            // 可选：POST 的请求体
  }
}

重要的 URL 格式：

baseUrl 必须有尾部斜杠：https://api.example.com/v1/
testEndpoint.path 不能有前导斜杠：users/me

选择端点时：

需要认证（以验证凭据有效）
轻量级（不获取大量数据）
快速返回（health/status 端点最理想）

常见模式：

me、user、profile - 用户信息端点
v1/status、health - 需要认证的状态端点
models、projects - 数据量最小的列表端点

公开 API（authType: 'none'） 不需要 testEndpoint - 我们通过访问 base URL 进行测试。

本地数据源

本地文件夹的文件系统访问。

{
  "type": "local",
  "provider": "obsidian",
  "local": {
    "path": "/Users/me/Documents/ObsidianVault"
  }
}

创建后，运行 source_test 验证路径存在且可访问。

permissions.json 格式

扩展此数据源探索模式权限的自定义规则。

{
  "allowedMcpPatterns": [
    {
      "pattern": "^mcp__linear__list",
      "comment": "允许在探索模式下列出资源"
    }
  ],
  "allowedApiEndpoints": [
    {
      "method": "GET",
      "path": "^/search",
      "comment": "允许探索模式下的搜索端点"
    },
    {
      "method": "POST",
      "path": "^/v1/query$",
      "comment": "允许仅查询端点的 POST"
    }
  ],
  "allowedBashPatterns": [
    {
      "pattern": "^ls\\s",
      "comment": "允许 ls 命令"
    }
  ]
}

图标处理

config.icon 字段控制数据源图标。解析优先级如下：

`config.icon` 值	行为
Emoji（例如 `"🔧"`）	渲染为 emoji 文本
本地路径 `"./icon.svg"`	从 `sources/{slug}/icon.svg` 加载
URL `"https://..."`	由 `source_test` 自动下载到本地 `icon.*` 文件
未定义/null	自动发现 `sources/{slug}/icon.{svg,png}`，回退到 favicon

最佳实践： 创建数据源时将 icon 设置为 URL。运行 source_test 下载并本地缓存它。然后应用使用本地文件进行快速、离线可用的显示。

常见提供商

Gmail

提供商：gmail，类型：api 通过 source_gmail_oauth_trigger 使用 OAuth。

Linear

提供商：linear，类型：mcp URL：https://mcp.linear.app，OAuth 认证。

GitHub

提供商：github，类型：mcp URL：https://api.githubcopilot.com/mcp/，bearer 认证（需要 PAT - OAuth 会失败）。

Exa (搜索)

提供商：exa，类型：api Base URL：https://api.exa.ai，使用 x-api-key 的 header 认证。

Brave Search

提供商：brave，类型：mcp 传输：stdio，命令：npx -y @modelcontextprotocol/server-brave-search，需要 BRAVE_API_KEY 环境变量。

Memory

提供商：memory，类型：mcp 传输：stdio，命令：npx -y @modelcontextprotocol/server-memory，无需认证。

工作流程

创建数据源

始终遵循对话式设置流程（见上文）。关键步骤：

创建前询问：了解用户意图、范围和常见任务
配置前研究：使用 WebSearch 查找文档、最佳实践、限制
根据上下文定制 guide.md：包含用户提到的特定项目/团队
完成前测试：验证配置，触发认证，验证连接

技术步骤：

创建数据源文件夹：

mkdir -p ~/.tentarc/workspaces/{ws}/sources/my-source

使用适当设置编写 config.json（见上文 schema）
根据用户上下文和用例编写 guide.md
为探索模式创建 permissions.json - 列出数据源的工具，识别只读操作（list、get、search），添加简单模式。模式自动限定到此数据源。
运行 source_test 验证配置并测试连接
如需认证，触发相应流程：
- MCP OAuth 用 source_oauth_trigger
- Gmail 用 source_gmail_oauth_trigger
- API keys/tokens 用 source_credential_prompt
向用户确认数据源按预期工作

测试数据源

使用 source_test 和数据源 slug：

验证 config.json schema
测试连接性
如需要下载图标
更新 connectionStatus

故障排除

"needs_auth" 状态：

数据源需要认证
使用适当的认证触发工具

"failed" 状态：

检查 config.json 中的 connectionError
验证 URL 正确
检查网络连接

图标不显示：

确保 iconUrl 有效
运行 source_test 重新下载
检查文件是否存在于数据源文件夹中