caspian-sdk

MCP办公协作

提供方 TryCaspian · 包名 caspian-sdk

办公协作 stdio · 本地进程 未标注 社区 / 第三方 Claude DesktopCursorClineClaude Code
查看接入方式

Agent communication SDK. The open-source agent communication layer for AI agents — email, WhatsApp, Slack, Discord, Telegram, SMS. Python & TypeScript.

一句话选型结论

按资料字段整理

caspian-sdk 属于办公协作类 MCP 服务器,stdio · 本地进程,鉴权方式未标注,可直接接入 Claude Desktop、Cursor、Cline 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类办公协作 传输方式stdio · 本地进程 鉴权未标注 部署方式本地部署
GitHub 星标 871 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

办公协作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

agent-communication agent-messaging ai-agent ai-agents communication

支持客户端

适用场景

agent-communicationagent-messagingai-agent

安装与配置

stdio · 本地进程 未标注
客户端在本机拉起子进程,数据不出本机
pip install caspian-sdk

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程与消息

查日程、发消息、约会议。

表单与审批

填表单、走审批流。

团队协作

同步任务、汇总进展。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Cursor、Cline,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在办公协作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
caspian-sdk当前 未标注 stdio · 本地进程 本地部署 有 2026-08-23
CowAgent 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Karakeep MCP 未标注 未标注 未标注 无 2026-05-17
agentscope 未标注 stdio · 本地进程 本地部署 有 2026-04-11
note-gen 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Everywhere 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

办公协作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方TryCaspian上游标注的维护方 TryCaspian
分类办公协作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时caspian-sdk · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-08-23上游最后核验时间

详细介绍

15.7 KB
来自项目仓库与上游目录的原文,未做删改

Website
PyPI
npm
SKILL.md for agents
Contributing

English · 简体中文

The largest OSS agent frameworks each built 25+ channel adapters — and still spend
8–15% of their issue trackers on channel plumbing. Caspian makes it one handler.


Caspian is an agent communication SDK. Your agent's reasoning decides what to say; Caspian is how it exists on Slack, Discord, Telegram, email, WhatsApp, X, Linear, and beyond — one channels.add() per channel, declarative rules for all of them, threading, webhook verification, and platform quirks handled.

Most agent communication work is agent-to-human, not agent-to-agent. Protocols like A2A and ACP connect agents to each other; Caspian connects your agent to the people it works for, on the channels they already use.

Version 1.0 is a full rewrite. The public surface is Caspian (not the legacy CommClient from 0.6.x). See Migrating from 0.6.x below.

Get started in 30 seconds

Building in a coding agent (Claude Code, Codex, Cursor, Kimi, …)? Paste this — it reads the live guide and does the whole integration for you:```text
Integrate Caspian so my agent can message people on email, Slack, Discord, Telegram, and more.
Read https://api.trycaspianai.com/SKILL.md and follow it end to end.


That's the fastest path — the guide at `/SKILL.md` is always current.

**Or set it up by hand:**```bash
pip install caspian-sdk        # Python 3.10+
npm install caspian-sdk        # TypeScript / Node 18+ / Bun

Get an API key from dashboard.trycaspianai.com, then:

Hosted — Caspian's gateway owns inbound; your process polls for events:```python
from caspian import Caspian

cx = Caspian(api_key="...") # or CASPIAN_API_KEY in .env
cx.channels.add("telegram", bot_token="...") # Telegram is BYO BotFather token

@cx.on_message({"overlap": "queue", "ack": "On it…"})
def handle(thread, msg, ctx):
thread.post(f"You said: {msg.text}")

cx.run() # polls the gateway — Ctrl+C to stop


**Self-host** — your process, your tokens, no gateway polling:```python
cx = Caspian()
cx.channels.add("telegram", via="self-host", bot_token="...",
                webhook_url="https://your.server/telegram")

@cx.on_message({"channel": "telegram"})
def handle(thread, msg, ctx):
    thread.post(f"You said: {msg.text}")

# from your HTTP route:
results = cx.handle("telegram", request_body, request_headers)

Discord and Slack can receive over a held-open socket instead of a public webhook — cx.listen("discord") (requires optional extra caspian-sdk[discord]).

TypeScript — same contract:```ts
import { Caspian } from "caspian-sdk"

const cx = new Caspian()

await cx.channels.add("telegram", {
via: "self-host",
botToken: process.env.TELEGRAM_BOT_TOKEN!,
webhookUrl: "https://your.server/telegram",
})

cx.onMessage({ channel: "telegram", overlap: "queue" }, async (thread, msg) => {
await thread.post(You said: ${msg.text})
})

// POST your webhook route → cx.webhooks.telegram(req)


Adding a channel is one more `channels.add()` call — handler rules stay the same.

### CLI

The rewrite CLI lives in `packages/cli` (TypeScript + Bun). It is a thin client of the same SDK surface — catalog discovers, `call` invokes:```bash
caspian init                 # mint a key → ~/.caspian/.env or project .env
caspian channels add telegram
caspian channels add telegram --via self-host --bot-token "$TG" \
  --webhook-url https://myapp.example.com/hook
caspian call post --thread telegram:123:456 --text "shipping now"
caspian threads tail telegram:123:456

See packages/cli/README.md for the full command map.

Delete your adapter layer

Without Caspian
With Caspian```python

slack_bolt app + socket handler

discord.py client + intents + reconnect

python-telegram-bot + webhook server

smtplib/imap polling + threading logic

4 auth flows, 4 payload shapes,

4 retry/backoff paths, 4 dedup caches,

per-channel identity bugs...

~1,500 lines before your agent

says a single word

``````python
cx.channels.add("email", via="self-host", ...)
cx.channels.add("telegram", via="self-host", bot_token=TG, webhook_url=URL)
cx.channels.add("slack", via="self-host", bot_token=SLACK, ...)

@cx.on_message({"overlap": "queue"})
def handle(thread, msg, ctx):
thread.post(agent(msg.text))

cx.run() # hosted

or cx.listen("slack") / cx.handle(channel, body, headers)


> **Using a coding agent?** Point it at `SKILL.md` — it can do the entire integration for you.

## The problem

Every agent team ends up rebuilding the same four things — and none of them make the agent smarter.

**1. You own infrastructure you never wanted.** Writing the Slack bot is a weekend; owning it is forever. Session/auth desync, reconnect loops, silent connection failures, payload changes on every platform version bump. The pain isn't `send()` — sending is a solved call. The pain is the **lifecycle**. The largest OSS agent frameworks each maintain 25+ channel adapters in-tree and still spend 8–15% of their issue trackers on channel plumbing. (We measured 42 open-source agent projects before writing a line of this code.)

**2. Communication isn't part of your agent's decision-making.** With one-off, per-channel integrations, a developer decided at build time where and how the agent talks. The agent itself can't reason *"this deserves a quick Telegram ping now and an email summary afterwards"* — each channel is a separate bot with separate code and a separate identity. Communication stays hardcoded plumbing instead of becoming a capability the model can actually decide with.

**3. You maintain N identities for every one person.** The same human DMs your agent on Instagram today and emails it tomorrow. Now *your* database needs its own concept of "this is one person, one relationship, one running conversation" — who said what on which channel, and what should happen next in the flow. Every team rebuilds that continuity layer from scratch, per app, and it never stops needing care.

**4. A single-channel agent is a competitive disadvantage.** If a competing agent is reachable on five channels and yours on one, users go where they get answered. The open-source numbers show it: the agents people actually rely on are exactly the ones deployed across dozens of human channels — and that reach is exactly where their engineering time goes.

## Caspian's answer

**Channels are transports, not identities.** The agent is one program (`cx.app.rules` is inspectable data); every channel binds through the same adapter interface, and your handler code works against a normalized `Thread` / `Message` model. Messages arrive as kernel events regardless of transport, overlap policies (`queue` / `debounce` / `drop` / `parallel`) serialize concurrent chats, and `thread.post()` / `thread.reply()` always answer in the right place.```mermaid
flowchart LR
    S[Slack] --> A
    D[Discord] --> A
    T[Telegram] --> A
    E[Email] --> A
    W[WhatsApp · Messenger] --> A
    X[X] --> A
    A["channel adapters<br/>verify · normalize · thread"] --> I["one agent program"]
    I --> H["your on_message rules"]
    H -->|"thread.post()"| I

Hosted or self-host, same code. via="hosted" (default) uses the Caspian gateway at https://api.trycaspianai.com — set CASPIAN_API_KEY and optionally CASPIAN_BASE_URL. via="self-host" runs adapters in your process with your platform tokens. Switch modes without rewriting handlers.

Features

🧵 Declarative rules, one program

@cx.on_message({"channel": "telegram", "command": "help"}) — filters for channel, chat kind, command, overlap, and instant ack. Your bot is data: cx.app.rules is inspectable and testable offline.

🔐 Webhook verification, always

Slack signing secret, Meta X-Hub-Signature-256, Telegram secret header, X CRC, and signed email webhooks. Mismatches rejected.

☁️ Hosted or self-host

Gateway polling with cx.run(), or bring your own tokens and webhooks/sockets with via="self-host". Same handler rules either way.

🧪 Offline fakes for every channel

Adapters consume each platform's real payload shapes — 650+ tests across Python + TypeScript, zero network in CI.

⌨️ Typing, streaming, rich sends

thread.typing(), thread.stream() (post once, edit as it writes), thread.send_media(), thread.send_blocks(), reactions, pins, forwards, and cold DMs.

🤖 Model tools from the same surface

cx.tools(thread) exposes the Command catalog (post, react, send-photo, …) with schemas derived from the kernel — same API your handlers use.

🔌 Per-channel packs (TypeScript)

Import caspian-sdk/telegram, caspian-sdk/discord, caspian-sdk/slack, and the rest for parse/plan/execute without pulling the whole facade.

📡 Socket inbound (Discord, Slack)

No public URL required — cx.listen("discord") or cx.listen("slack") over a held-open websocket (optional extras).

Channels

Self-host adapters ship in the SDK for the channels below. Hosted mode covers any channel the gateway supports (including Bluesky, Instagram, and channels with no local adapter).

Channel Self-host (via="self-host") Hosted (via="hosted")
Telegram (bot) ✅ webhook or poll ✅ BYO bot token
Discord ✅ socket ✅
Slack ✅ socket or webhook ✅
Email ✅ ✅ instant inbox
WhatsApp Business ✅ ✅ one-click
Facebook Messenger ✅ ✅
X / Twitter ✅ * ✅
📶 SMS · voice (Twilio) ✅ ✅ no hardware
iMessage ✅ ✅
Linear ✅ —
Bluesky — ✅
Instagram DM — ✅
  • The fine print — read before you promise features

  • X is not free: DM send/receive needs a paid X API subscription on your X developer app (the free tier is write-only and capped).

  • GSM modem SMS: your own modem + SIM; carrier compliance (A2P rules) is on you.

Where to use it

If your agent needs to talk to humans, this is the layer under it:

  • Customer support agents — answer on email, Slack, Instagram DM, or wherever the customer opened the thread; hand off to a human without dropping context.
  • Sales & lead follow-up — first touch on the channel the lead used, follow-ups where they actually respond.
  • Personal / executive assistants — one assistant identity across your email, Telegram, and Slack instead of three disconnected bots.
  • Community & product bots — the same agent in your Discord, your Slack community, and members' DMs.
  • OpenClaw agents — clawhub install @trycaspian/caspian (the skill) teaches your agent to wire itself up; openclaw-caspian is the native channel plugin.
  • OpenCode agents — caspian-opencode-plugin bridges Caspian email / Telegram / Discord into OpenCode sessions. Details: packages/opencode.

Start from a runnable example — one folder per channel, shared handlers in app.py / app.ts.

Recipes

Same agent, three channels:```python
cx.channels.add("email", display_name="Acme Support")
cx.channels.add("telegram", bot_token=BOT_TOKEN)
cx.channels.add("slack", bot_token=SLACK_TOKEN, signing_secret=SLACK_SECRET)

the @cx.on_message rules you already wrote now answer on all three

cx.run()


**Filter by command and chat kind:**```python
@cx.on_message({"channel": "telegram", "command": ["start", "help"]})
def help_menu(thread, msg, ctx):
    thread.post("Commands: /help /status /ping")

@cx.on_message({"channel": "telegram", "kind": "dm"})
def dm_only(thread, msg, ctx):
    thread.post(f"DM from {msg.sender}: {msg.text}")

Streaming reply:```python
@cx.on_message({"channel": "telegram", "overlap": "stream"})
def stream_story(thread, msg, ctx):
with thread.stream(min_chars=1, throttle=0.25) as out:
for chunk in ["Once ", "upon ", "a time…"]:
out.append(chunk)


**Callback buttons:**```python
@cx.on_action({"channel": "telegram", "data": "help"})
def on_help_button(thread, action, ctx):
    thread.post("You tapped Help.")

Rich messages

Send blocks through thread.send_blocks() — each channel renders its best native shape (Slack Block Kit, Discord embeds, Telegram keyboards) and text-only channels degrade automatically.```python
from caspian import Button

thread.send_blocks(
(),
text="Order #1024 shipped — arriving Thursday.",
actions=(
Button(label="Track package", url="https://example.com/track/1024"),
Button(label="Get help", data="help:1024"),
),
)
``````typescript
await thread.sendBlocks([], {
text: "Order #1024 shipped — arriving Thursday.",
actions: [
{ label: "Track package", url: "https://example.com/track/1024" },
{ label: "Get help", data: "help:1024" },
],
})


## What's in this repo

| Package | |
|---|---|
| `packages/python` | `caspian-sdk` (PyPI) — Python client: `Caspian`, `channels.add()`, `@on_message` / `@on_action`, hosted + self-host adapters. Import: `from caspian import Caspian`. |
| `packages/typescript` | `caspian-sdk` (npm) — TypeScript client: same contract, camelCase API, per-channel subpath exports. |
| `packages/cli` | `@caspian/cli` — Bun CLI: `init`, `channels add`, `catalog`, `call`, `threads tail`. |
| `packages/openclaw` | `openclaw-caspian` — OpenClaw channel plugin. |
| `packages/opencode` | `caspian-opencode-plugin` — OpenCode plugin. |
| `packages/clawhub-skill` | The ClawHub skill — publishes the live gateway SKILL.md. |
| `examples` | One self-host example per adapter; `examples/telegram/hosted.py` for hosted Telegram. |

Package READMEs have the full API surface: `packages/python/README.md`, `packages/typescript/README.md`.

## Migrating from 0.6.x

The 0.6.x `CommClient` API (`from caspian_sdk import CommClient`, `connect_*()`, `message.reply()`) is a different SDK. It remains published on PyPI/npm; its source is tagged `legacy-sdk-0.6.x` in this repository.

| 0.6.x | 1.0 |
|---|---|
| `CommClient()` | `Caspian()` |
| `client.connect_telegram(...)` | `cx.channels.add("telegram", ...)` |
| `@client.on_message` / `message.reply()` | `@cx.on_message({...})` / `thread.post()` |
| `client.listen()` | `cx.run()` (hosted) or `cx.handle()` / `cx.listen()` (self-host) |

There is no drop-in migration path — new projects should start on 1.0.

## Starter templates

Ready-to-run repos — click "Use this template", add a token, and your agent is live on the channel:

| Template | Channel | Language |
|---|---|---|
| `telegram-ai-agent-template` | Telegram | Python |
| `discord-ai-agent-template` | Discord | Python |
| `slack-ai-agent-template` | Slack | Python |
| `email-ai-agent-template` | Email (instant inbox) | Node.js |
| `openclaw-telegram-agent` | OpenClaw + Telegram | guide |

## Roadmap

- **MCP server** — connect and message channels straight from any MCP-capable agent
- **Reddit & LinkedIn adapters** — next channels in the pipeline
- **Agent-native payments** — pay-as-you-go via API, x402-ready, no dashboard
- **More adapters** — the interface is small on purpose; add one

## Community & support

- **Questions, ideas, show & tell** — GitHub Discussions
- **Bugs** — GitHub issues
- **Security** — see SECURITY.md (please, no public issues for vulnerabilities)
- **Hosted product & contact** — trycaspianai.com

## Development```bash
git clone https://github.com/TryCaspian/caspian-sdk.git
cd caspian-sdk && uv sync
uv run pytest                              # Python SDK tests (packages/python)
uv run ruff check .
cd packages/typescript && bun install && bun run ci   # typecheck + lint + 235 tests
cd ../cli && bun install && bun run ci                # CLI tests

Contributions welcome — see CONTRIBUTING.md.

If Caspian saved you time, a star helps other agent builders find it. ⭐

License

Apache-2.0 for this repository. The caspian-sdk package on PyPI is MIT.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
caspian-sdk 怎么安装?

在客户端按下面的安装命令接入:pip install caspian-sdk。对应的包名是 caspian-sdk。装完在客户端配置里引用同一个包或端点。

caspian-sdk 怎么在 Claude Desktop、Cursor、Cline 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

caspian-sdk 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

caspian-sdk 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

caspian-sdk 支持哪些客户端?

资料标注支持 Claude Desktop、Cursor、Cline、Claude Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

caspian-sdk 能提供哪些能力?

资料显示能力标签包括 agent-communication、agent-messaging、ai-agent、ai-agents、communication。具体工具清单以官方文档为准。

caspian-sdk 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

caspian-sdk 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-08-23。