@ hasna/ 连接器
开源连接器平台,用于启用,认证,并从一个包运行API连接器.
安装
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.jsonconnectors 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_URL | PostgreSQL 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_KEY | Base64, 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_BIND | 1 让 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(中文(简体) )
是公开的.
符号按此顺序解决, 并且从未打印 :
HASNA_CONNECTORS_SERVE_TOKEN在环境中.- 只有所有者的文件
<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 - 见 自由主义