@hasna/connectors

中文文档
1.8.0发布于 2026/10/17Apache-2.0TypeScriptES Module近 30 天下载 4.7万

开源连接器库 - 用单一命令安装 API 连接器

中文使用文档
文档目录15 节
  1. 安装
  2. 这是什么
  3. 本地或远程
  4. 国 际
  5. 压缩输出默认值
  6. MCP 服务器
  7. HTTP 模式
  8. 运行自己的服务器
  9. 本地 REST API (英语: /api (中文(简体) )
  10. 认证
  11. SDK (英语: @hasna/connectors/sdk (中文(简体) )
  12. 项目布局
  13. 数据目录
  14. 撰稿人笔记
  15. 许可证

@ hasna/ 连接器

开源连接器平台,用于启用,认证,并从一个包运行API连接器.

npm License

安装

bun install -g @hasna/connectors

这是什么

@hasna/connectors 单产品运行时间 :

  • 连接器停留在这个 repo 和软件包内
  • 工程启用他们想要的连接符 .connectors/manifest.json
  • 证书在连接器数据之家(由包件溶解器解决); ~/.hasna/connectors/ 直到 XDG 数据之家被采用)
  • CLI, MCP, REST, 以及本地的API/ OAuth 服务器都使用相同的连接器注册

本地或远程

连接器默认在本地运行, 无任何配置: CLI, MCP 服务器和 SDK 在进程中运行连接器引擎,并保持连接 当地商店.

使用服务器(一个您自己运行, 或任何会说话的服务) /v1 API 密码),指向客户端:

# One shell or CI job: environment variables
export CONNECTORS_API_URL=https://connectors.example.com
export CONNECTORS_API_KEY=...            # from your server administrator

# Or save it: the key is read from stdin or a hidden prompt, never from arguments
connectors login --api-url https://connectors.example.com
connectors config show                   # mode, server URL, whether a key is set
connectors logout                        # delete the stored key
connectors config unset api-url          # back to local mode

设置按此顺序解决: --api-url 编号 : --api-key-stdin 旗帜,然后 CONNECTORS_API_URL 编号 : CONNECTORS_API_KEY,则 <connectors home>/config.json (模式) 0600时 connectors login),然后是本地模式。 保存的密钥是 只被发送到它保存的服务器上,没有密钥的服务器 URL 是 错误而非静态返回到本地模式, plain http:// 实值 拒绝任何回扣,除非 CONNECTORS_ALLOW_INSECURE_HTTP=1。 。 。 .

服务连接器在两种模式中工作方式相同:

connectors service list
connectors service describe openai       # auth methods, operations and their effects
printf '{"adminKey":"%s"}' "$OPENAI_ADMIN_KEY" | \
  connectors connections add openai --auth admin_key --label prod-admin --secrets-stdin
connectors connections add openai --auth admin_key --label ci --secret-env adminKey=OPENAI_ADMIN_KEY
connectors connections list
connectors connections check openai:prod-admin
connectors call openai <operation> --connection prod-admin --input '<json object>'
connectors runs list --limit 20

发送的服务连接器是 anthropic, (中文(简体) ), brandsight, (中文(简体) ), cloudflare, (中文(简体) ), cursor, (中文(简体) ), godaddy, (中文(简体) ), openai, (中文(简体) ), opencode, (中文(简体) ), stable 财务报告和审定财务报表 youtrust (你们相信, 签名:签名请求、文件、收件人、审计线索和 网点; 见 文件/提供者/你的信任A级 您信任连接用平地选择环境 :

connectors connections add youtrust --auth api_key --label prod \
  --field environment=production --secret-env apiKey=YOUTRUST_API_KEY   # default: sandbox
connectors call youtrust signature_requests.list --connection prod --input '{"limit":10}'

保密连接字段从不被接受为参数( Name--field 拒绝 它们); 使用 --secret-env key=ENV_NAME, (中文(简体) ), --secrets-stdin 或者隐藏的提示. 非读取的操作( E)write, (中文(简体) ), billable, (中文(简体) ), destructive, (中文(简体) ), credential需求 --confirmA级 credential 结果,例如新铸造的 键,会显示一次且从未存储.

国 际

connectors --help

典型流量 :

connectors install github stripe
connectors auth github
printf '%s\n' "$STRIPE_API_KEY" | connectors auth stripe --key-stdin
connectors run github --help
connectors run stripe products list --limit 5

密钥命令 :

  • connectors install 写入工程启用到 .connectors/manifest.json
  • connectors list 财务报告和审定财务报表 connectors search 浏览共享目录
  • connectors docs 从内部登记册读取连接器文件
  • connectors auth 将证书存储在连接器数据之家(由包件解析器解决)
  • connectors auth <name> --key-stdin 从 Stdin 读取 API 密钥或无记名符号 --key-env <VAR> 从命名的环境变量读取. connectors setup 财务报告和审定财务报表 connectors llm set 一样 两旗 不要通过密钥作为命令行值: 它降落在 shell 历史和进程列表中 .
  • connectors run 执行单产品运行时的连接器命令
  • connectors status 财务报告和审定财务报表 connectors doctor 验证设置和认证状态

压缩输出默认值

CLI 输出默认是紧凑的, 所以代理终端不会充满巨大的 目录,README部分,证书状态表,或API记录.

  • connectors list 显示一个紧凑的页面。 使用 --cursor <n> 或者说 --offset <n> 下一页, --limit <n> 更改页面大小, --verbose 扩大范围 行,或 --all --verbose 为完整的人类目录. --json 现在返回 a 精密的20行信封, 有真实的 total, (中文(简体) ), limit, (中文(简体) ), cursor, (中文(简体) ), next_cursor,以及 has_more; 使用 --json --verbose 用于全域 限制页面,或 --json --full 编号 : --json --all 留下的遗产 阵列。 超过100分的受约束JSON限值在完全输出指导下被拒绝.
  • connectors docs <name> 显示一个摘要。 使用 --verbose 用于全解析 节, --essential 仅限认证/env vars, --raw 原始标记,或 --json 用于结构化文件.
  • connectors status, (中文(简体) ), connectors doctor, (中文(简体) ), connectors jobs list, (中文(简体) ), connectors workflows list, (中文(简体) ), connectors whoami,并使用干线安装输出 页面或默认缩短人行。 使用 --verbose, (中文(简体) ), show编号 :inspect,或 --json 当需要全部细节时.
  • connectors run 保留 JSON 风格的命令输出, 但切换非常大 人类的出击。 使用 connectors run --verbose <connector> ... 给全垒打.

MCP 服务器

connectors-mcp

MCP工具也使用紧凑默认. list_connectors, (中文(简体) ), list_jobs, (中文(简体) ), list_workflows,以及 list_agents 返回页中的对象 count, (中文(简体) ), total, (中文(简体) ), limit, (中文(简体) ), cursor, (中文(简体) ), nextCursor,以及 hasMore; 通过 cursor 继续, limit 更改页面大小,以及 verbose: true 完全记录. list_connectors 页收取绕行可选概率输出剥取, 因此无法删除延续元数据. connector_docs 和作业发现 返回摘要,除非 verbose: true 或请求特定的细节路径.

服务连接工具通过与CLI(本地,或 服务器从 CONNECTORS_API_URL 编号 : connectors login: connectors_service_list, (中文(简体) ), connectors_service_describe, (中文(简体) ), connections_list, (中文(简体) ), connections_check, (中文(简体) ), connectors_call (通过) confirm: true 对于任何非读取)和 runs_list中,没有工具接受一个秘密值;与 CLI 或 API,因此生密钥从不通过代理工具参数. 何时 connectors_call 运行 a credential 操作(一个薄荷键), 其结果中的秘密值(key, (中文(简体) ), token, (中文(简体) ), secret, (中文(简体) ), api_key, (中文(简体) ), access_token, (中文(简体) ), refresh_token, (中文(简体) ), client_secret, (中文(简体) ), value,在任何深度)来 恢复为 [redacted: pass reveal_secret=true to return it] 除非电话 套装 reveal_secret: true。 。 connectors call 仍然打印 值,一次,有一个警告.

HTTP 模式

connectors-mcp --http            # http://127.0.0.1:8808/mcp
MCP_HTTP=1 connectors-mcp

卫生: GET http://127.0.0.1:8808/health. MCP 也安装在 connectors-serve 时间 /mcp。 。 。 .

运行自己的服务器

connectors-serve 服务于 /v1 API 密码 国家行动倡议、混合国家方案 服务器和SDK在远程模式中使用.

connectors-serve                         # http://127.0.0.1:9876, SQLite in the connectors home
PORT=8080 connectors-serve
connectors-serve --host 0.0.0.0          # shared server: needs CONNECTORS_DATABASE_URL (containers, behind TLS)

只有回回转上的 SQLite 服务器处于本地模式( 服务器令牌, 私人) base_urls,当地 /api/* (原始内容存档于2018-10-21). routes. PostgreSQL, 或任何非循环 地址, 是公共模式: 仅租户 API 密钥, 公开 https base_url编号 只有他们的宿主,在每一个供应者的要求之前,已判决他们, 而 OAuth 仅使用 CONNECTORS_PUBLIC_URL。一个 SQLite 服务器拒绝 除非 CONNECTORS_ALLOW_SQLITE_ON_PUBLIC_BIND=1。 。 。 . 限制服务器的网络进取(拒绝元数据地址, 链接本地、 回回和私有区域: DNS 检查无法停止名称 在检查和请求之间更改答案.

设置目的
PORT 编号 : CONNECTORS_PORT要监听的端口( 默认) 9876) (中文(简体) ).
CONNECTORS_HOST要绑定的接口( 默认) 127.0.0.1· ; --host (原始内容存档于2017-03-25). overse.
CONNECTORS_DATABASE_URLPostgreSQL DSN (英语). 取消设置: SQLite at <connectors home>/connectors.db常规 DATABASE_URL 被忽略。 TLS 跟随DSN的 sslmode· ; CONNECTORS_DATABASE_CA_FILE 针接CA捆.
CONNECTORS_DATABASE_STATEMENT_TIMEOUT_MS邮递SQL statement_timeout 集合连接( 默认) 15000) (中文(简体) ).
CONNECTORS_ENCRYPTION_KEYBase64, 32字节. 加密存储的证书(AES-256-GCM). 本地模式生成 <connectors home>/encryption.key (模式) 0600相反。 它的指纹按密钥版本记录;一个服务器以不同的密钥开始,用于被记录版本,拒绝启动.
CONNECTORS_ADMIN_KEY启用管理路径( 至少24个字符) 。 未设置:他们返回404.
CONNECTORS_API_KEY_SIGNING_SECRET存储的API- key hashes 可选 HMAC 密钥 .
CONNECTORS_ORIGIN_AUTH 编号 : CONNECTORS_ORIGIN_AUTH_HEADER可选共享秘密( 至少 24 个字符) 前置网关必须发送的 /v1。 。 。 .
CONNECTORS_PUBLIC_URL公用基址, 用于 OAuth 重定向 URI 和相对 redirect_after 路径。 公共模式下 OAuth 要求 .
CONNECTORS_OAUTH_REDIRECT_ORIGINS逗号分隔的准确来源( 例如) https://app.example.com)绝对 OAuth redirect_after 也许可以使用.
CONNECTORS_ALLOW_SQLITE_ON_PUBLIC_BIND1 让 SQLite 服务器绑定一个非浏览地址;然后在公共模式下运行.
CONNECTORS_BASE_PATH接受在倒置前缀下的请求, 例如 /connectors。 。 。 .

迁移经过版本和验收。 在开始前应用,或让 服务器启动时应用它们 :

connectors-serve migrate
connectors-serve --migrate

租户和 API 密钥由服务器自己的 CLI 管理( 环境相同 ) 服务器,来自环境的秘密, 绝不来自参数 :

connectors-serve admin create-tenant acme
connectors-serve admin create-key <tenantId> --label ci     # the key is printed once
connectors-serve admin list-tenants
connectors-serve admin revoke-key <keyId>

或者通过管理员 API Authorization: Bearer <CONNECTORS_ADMIN_KEY>数字 : POST /v1/admin/tenants, (中文(简体) ), POST /v1/admin/tenants/{id}/keys, (中文(简体) ), GET /v1/admin/tenants/{id}/keys 财务报告和审定财务报表 DELETE /v1/admin/keys/{id}。给出每个 使用他们的密钥; 它们运行 connectors login --api-url <your server>。 。 。 .

在 Docker 中, 在 Bun 图像上安装软件包并运行 connectors-serve,与 PostgreSQL 和加密密钥作为环境变量传递 :

FROM oven/bun:1
RUN bun install -g @hasna/connectors
ENV PORT=9876 CONNECTORS_HOST=0.0.0.0
EXPOSE 9876
CMD ["connectors-serve", "--migrate"]
docker run -p 9876:9876 \
  -e CONNECTORS_DATABASE_URL -e CONNECTORS_ENCRYPTION_KEY -e CONNECTORS_ADMIN_KEY \
  my-connectors-server

容器必须在非回放接口上收听(CONNECTORS_HOST=0.0.0.0(中文(简体) ) 让已公布的端口到达它。 把 TLS 放在服务器前( 反向) 由于客户拒绝普通 http:// 除了其他任何东西 循环回放. 包裹是自己的 Dockerfile 从 预建 bin/serve.js 捆绑( e)bun run build (第一编).

本地 REST API (英语:/api(中文(简体) )

本地的 REST API 提供一次性产品运行时间 http://127.0.0.1:9876 (只有默认情况下).

认证

每个 /api/* 路径和 /mcp 挂载需要一个无记名符号 : Authorization: Bearer <token> (或 X-Connectors-Token: <token>) (中文(简体) ). GET /api/export 返回每个已配置的供应商证书, 因此服务器 永远不回答,或者其他的 /api/ - 匿名的 - 匿名的. /health 和 OAuth 浏览器路由(/oauth/:name/start, (中文(简体) ), /oauth/:name/callback(中文(简体) ) 是公开的.

符号按此顺序解决, 并且从未打印 :

  1. HASNA_CONNECTORS_SERVE_TOKEN 在环境中.
  2. 只有所有者的文件 <connectors home>/serve-token (模式) 0600默认值 ~/.hasna/connectors/serve-token),第一个启动时生成.

这个 connectors CLI , (英语), connectors-mcp 编辑 ./sdk 客户端读取相同的两个 源,所以没有配置的框认证符上的相同用户进程 当远程或其他用户进程获得时 401 CONNECTORS_SERVE_UNAUTHORIZED。 。 。 . 没有匿名模式。 要故意在另一个界面上听,请打电话 startServer(port, { hostname })。 。 。 .

SDK (英语:@hasna/connectors/sdk(中文(简体) )

此包件内的 SDK 类型脚本船作为 ./sdk 导出子路径 (每个应用程序一个软件包——没有单独的 -sdk 软件包; 前者 @hasna/connectors-sdk 被这个子路径所取代). 是HTTP客户端 仅限(ConnectorsApiClient, (中文(简体) ), createHttpBackend, (中文(简体) ), BackendError 编辑 ),它运行在节点和 Bun:已建成 dist/sdk/index.js 进口 节点仅建出, 绝不是本地引擎或 bun:sqlite。 。 。 .

本地模式,并按 CLI 的方式解决后端,需要 Bun 和 住在这里 @hasna/connectors/local (单位:千美元)resolveBackend, (中文(简体) ), createLocalBackend, (中文(简体) ), describeMode; 包主条目再出口. 每个条目是其 自己的捆绑,所以检查 instanceof BackendError 与条目的类 你打电话来./sdk 页:1 ConnectorsApiClient, (中文(简体) ), ./local 页:1 resolveBackend),或比较 err.code。 。 。 .

import { ConnectorsApiClient, BackendError } from "@hasna/connectors/sdk";

// Any server that speaks the /v1 API (Node or Bun)
const client = new ConnectorsApiClient({
  baseUrl: "https://connectors.example.com",
  apiKey: process.env.CONNECTORS_API_KEY!,
});
const connections = await client.listConnections({ connector: "openai" });
// Bun only: resolve like the CLI (flags/env, then the saved config, then local mode)
import { resolveBackend, BackendError } from "@hasna/connectors/local";

const backend = await resolveBackend();
try {
  const { result, run_id } = await backend.run({
    connector: "openai",
    operation: "<operation>", // a name from (await backend.getConnector("openai")).operations
    connection: "prod-admin",
    input: {},
  });
} catch (err) {
  if (err instanceof BackendError && err.code === "CONFIRMATION_REQUIRED") {
    // not a read operation: pass confirm: true once the action is approved
  }
}

LocalConnectorsClient (及其别名) ConnectorsClient)),他们说话 当地 /api 路线,以及 HostedConnectorsClient 仍然为 兼容性,但被折旧为偏好 ConnectorsApiClient 财务报告和审定财务报表 resolveBackend (从) @hasna/connectors/local) (中文(简体) ).

项目布局

项目本地启用为轻量级:

.connectors/
├── manifest.json
└── index.ts

软件包不再将完整的连接器源树复制到每个工程中.

数据目录

接通器数据之家由包内解析器(XDG/macOS家用布局)解决. 遗产 ~/.hasna/connectors/ 默认保存有效数据之家,直到存储实际迁移到 XDG 数据之家(~/.local/share/hasna/connectors 在 Linux 上,与 connectors.db 或操作员设置数据类型覆盖 HASNA_DATA_HOME。精确的应用程序覆盖 HASNA_CONNECTORS_DIR 无条件获胜。 现有的活店在升级时永远不会变得隐形.

撰稿人笔记

一还原/一产品模式的促进者指导生活在 文档/一还原一产品. md。 。 。 .

许可证

Apache-2.0 - 见 自由主义

版本与发布记录

@hasna/connectors 共发布 149 个版本,首次发布于 2026/02/14;过去 12 个月发布了 149 个版本。

版本发布日期距今
1.8.0latest2026/10/171 个月前
1.7.02026/10/151 个月前
1.6.02026/10/141 个月前
1.5.02026/10/141 个月前
1.4.82026/09/271 个月前
1.4.72026/09/201 个月前

关于 @hasna/connectors 的常见问题

@hasna/connectors 是什么?

开源连接器库 - 用单一命令安装 API 连接器

如何安装 @hasna/connectors?

在项目目录运行 npm install @hasna/connectors,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 connectors、connectors-mcp、connectors-serve,可以用 npx connectors 直接运行。

@hasna/connectors 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hasna/connectors 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hasna/connectors 可以商用吗?

@hasna/connectors 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hasna/connectors 的下载量有多少?

根据 npm 官方下载统计,@hasna/connectors 在 2026/10/18 – 2026/11/16 这 30 天内被下载 47,411 次,日均约 1,580 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hasna/connectors 还在维护吗?

最新版本 1.8.0 发布于 2026/10/17(1 个月前);至今共发布 149 个版本,其中过去 12 个月发布了 149 个;首次发布于 2026/02/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。