mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-08 11:13:44 +02:00
f77fcbf4bf
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Research agents need current web information. > - The Apps catalog connects agents to remote MCP tools through the normal access rules. > - Telem.AI supplies web search and page reading through one API key. > - This PR adds its catalog entry, optional search settings, artwork, and setup guide. > - The connection keeps an operator's saved header policy when they reconnect. ## Linked Issues or Issue Description Refs #15302. Related catalog work: #13881. This PR continues #15302 by Yifei Ai (@aiwen324). Thank you for the connector and its review fixes. All seven original commits are preserved. GitHub denied the attempt to push to the contributor's fork, so this branch retains the repair commit and merges current master. Master now includes the same test fix. For a squash merge, keep the original author in the final commit message: ```text Co-Authored-By: Yifei Ai <aiwen324@users.noreply.github.com> Co-Authored-By: Paperclip <noreply@paperclip.ing> ``` A search found no separate public Telem issue or competing Telem PR. The existing Apps path matches the roadmap. **Agent or provider** Telem.AI provides web search and page reading through a hosted MCP server. **Why this adapter is useful** Agents can use multiple search providers through one governed connection. Operators can set the search tier, auto routing, and provider lists. **How the agent is invoked** The remote MCP server uses Streamable HTTP at `https://mcp.telem.ai/mcp`. The API key uses an `Authorization: Bearer` header. See the [official MCP guide](https://docs.telem.ai/integrations/mcp/). ## What Changed - Add the Telem.AI definition, research entry, permission review, and generated registry entry. - Add four optional settings. Unset settings send no request header. - Add official light and dark artwork, source records, and a setup guide. - Forward company, issue, agent, run, project, and correlation IDs by default. Preserve a saved policy, including disabled forwarding, on reconnect. - Add catalog and connection tests. ## Verification Current head: `b4164477fb1b312a504789bf17b51c963244c0fd`. Merged master: `228f0e2807c5b59d2aa129cf2d80b9777ebabf07`. - Resolved five shared catalog conflicts after the Superagent connection merged. - Keep both providers in the research ledger, generated registry, generator, branding manifest, and connection guide index. - Correct the combined catalog totals: 52 self-serve candidates, 55 research entries, and 68 Apps entries. - The published Git tree exactly matches the tested local resolution. - Catalog and Apps UI suites: **295 tests pass** after the catalog count fixes. - Connection service suite: **387 tests pass** in the full run. Its only failure was the old catalog count. That test passes on a focused rerun after the fix. This gives **388 passing service tests** across the two runs. - Total focused coverage: **683 passing tests**. The first runs exposed four fixed-count assertions that needed the combined totals. - Shared package build and plugin SDK compile pass. Token gates and whitespace checks pass. - Generation with `--definitions-only` reproduces the Telem definition and registry. The unrelated AgentMail and Linear drift remains excluded. - Local UI typecheck ended with exit 137 at the container memory limit. Full local typecheck, test, and build are not claimed. Earlier runs also recorded missing Cargo and Node development headers. - GitHub reports a clean merge state against master `228f0e280`. - All 54 checks are complete: **52 passed and two Storybook checks skipped**. No check failed or remains pending. - [CI](https://github.com/paperclipai/paperclip/actions/runs/37545412406) passes on this head. This includes typecheck, build, tests, browser shards, Runner checks, and Canary Dry Run. - [Greptile](https://github.com/paperclipai/paperclip/pull/15379#issuecomment-6024519537) is **5/5 on this head**. There are no review threads, open P2s, recommendations, or follow-ups. - [Superagent](https://github.com/paperclipai/paperclip/runs/112548142930) passes. - Final recovery checks confirm all seven original commits and current master remain in history. Token gates and whitespace checks pass. - The final recovery run makes no source change. It verifies the published repair and retains the local check limits below. - [Commitperclip](https://github.com/paperclipai/paperclip/actions/runs/37545407943) passes with no failures. Its only informational note asks the merger to keep the author trailer above. - All seven original contribution commits remain in history. The diff against master contains the same 14 Telem files. It adds no dependency, lockfile, schema, or workflow change. - The managed GitHub CLI capability was missing in this run. The installed GitHub connection applied the base files, merged master, then restored the tested combined catalog. No history was rewritten. The previous head `2d32a0094` passed all remote gates and had Greptile 5/5. Those results do not verify this new head. The original PR reports live setup, discovery, settings headers, gateway calls, and context-header forwarding. This repair does not repeat those account-bound checks. The permission record still marks maintainer live qualification as outstanding. ## Risks - Telem.AI receives the six context IDs by default. The saved header policy controls forwarding. Search use is billed to the account that owns the key. - All agents on a connection share its search settings. - The merge uses master's route-test setup unchanged. The company-boundary assertions remain intact. - No schema, dependency, or workflow change is included. - Live provider evidence is attributed to the original contributor. Maintainer live qualification remains outside this CI repair. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Original contribution: Anthropic Claude Opus 5.5 (`claude-opus-5-5`), 1M-token context, through Claude Code with shell, editing, and test tools, as disclosed in #15302. - CI repair and review: OpenAI `gpt-6-astra`, through Codex with reasoning, shell, editing, and GitHub tools. The runtime does not expose the context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Yifei Ai <aiwen324@gmail.com> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
# Telem.AI connection
|
|
|
|
Updated: 2026-10-03. Status: catalog definition added. The API key method was
|
|
verified on a local instance: setup, catalog discovery, gateway `tools/list`
|
|
and one read-only `tools/call`. Live account qualification by a maintainer is
|
|
outstanding.
|
|
|
|
Paperclip connects to the Telem.AI hosted MCP server at
|
|
`https://mcp.telem.ai/mcp`. Telem.AI gives agents web search and page fetch
|
|
across many search providers with one API key.
|
|
|
|
The connection has one method: a Telem API key stored as a Paperclip secret
|
|
and sent as an `Authorization: Bearer ...` header. Telem.AI does not offer
|
|
browser sign-in or a keyless profile.
|
|
|
|
The curated connection adds branding, guidance and four optional settings.
|
|
None of it is required to reach the server. Telem.AI can also be connected
|
|
from **Connect your own MCP server** with the same URL and header. See
|
|
[Connecting any remote MCP server](./GENERIC-REMOTE-MCP.md).
|
|
|
|
## Service involvement
|
|
|
|
Telem.AI hosts the MCP resource. Paperclip ID and Paperclip Connect do not
|
|
take part. Cloud and self-hosted instances use the same path. There is no
|
|
OAuth flow and no Paperclip callback.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
actor A as Administrator
|
|
participant P as Paperclip
|
|
participant T as mcp.telem.ai
|
|
|
|
A->>P: Paste a Telem API key and optional settings
|
|
P->>P: Store the key as a company secret
|
|
P->>T: tools/list with Authorization Bearer and X-Telem headers
|
|
T-->>P: Telem tool catalog
|
|
Note over P,T: Each agent tool call goes through the Paperclip gateway
|
|
P->>T: tools/call with the same headers
|
|
T-->>P: Tool result
|
|
```
|
|
|
|
| Purpose | Endpoint |
|
|
| --- | --- |
|
|
| MCP resource | `https://mcp.telem.ai/mcp` |
|
|
| API keys | `https://app.telem.ai` |
|
|
| Documentation | `https://docs.telem.ai` |
|
|
| Authorize, token, registration | none (API key only) |
|
|
| Paperclip callback | n/a |
|
|
|
|
## Administrator setup
|
|
|
|
1. Create an API key in the Telem console at `app.telem.ai`.
|
|
2. In Paperclip, open **Apps**, choose **Telem.AI**, and paste the key.
|
|
3. Optional: open **Advanced** and set the settings below.
|
|
4. Choose which agents get access, then finish.
|
|
5. To verify, open the connection's **Permissions** page and click **Test**
|
|
beside `telem_providers`. It is read-only and returns the list of available
|
|
search providers.
|
|
|
|
No callback URL, client registration or instance feature flag is needed.
|
|
|
|
## Settings
|
|
|
|
All settings are optional and apply to every agent that uses this connection.
|
|
Paperclip sends each one as a request header. It leaves a header out when its
|
|
setting is empty.
|
|
|
|
| Setting | Values | Header |
|
|
| --- | --- | --- |
|
|
| Auto routing | Off, Accuracy | `X-Telem-Auto-Routing` |
|
|
| Tier | Minimalist, Default, Extended, Max | `X-Telem-Tier` |
|
|
| Providers to include | comma-separated provider names | `X-Telem-Providers-Include` |
|
|
| Providers to exclude | comma-separated provider names | `X-Telem-Providers-Exclude` |
|
|
|
|
The setup form cannot clear a select after a value is chosen. To turn auto
|
|
routing off again, select **Off**. **Default** is the server's default tier.
|
|
|
|
## Resource filters
|
|
|
|
None. Telem.AI tools read public web content and do not act on customer
|
|
resources.
|
|
|
|
## Actions
|
|
|
|
| Tool | Risk | Purpose |
|
|
| --- | --- | --- |
|
|
| `telem_search` | read | Search the web across providers |
|
|
| `telem_fetch` | read | Read the content of known URLs |
|
|
| `telem_providers` | read | List the available search providers |
|
|
| `telem_session_history` | read | Read earlier results of a search session |
|
|
|
|
Usage is billed to the Telem account that owns the API key.
|
|
|
|
## Manifest
|
|
|
|
- slug `telem`, name `Telem.AI`, category `ai`, risk tier `S2`
|
|
- method `mcp-api-key`: `mcp_remote`, `api_key`, `keyPlacement`
|
|
`Authorization` with prefix `Bearer `
|
|
- `tenantFields`: `autoRouting`, `tier`, `providersInclude`,
|
|
`providersExclude` (all optional, all header transport)
|
|
- branding: the official Telem mark, `ui/public/brands/apps/telem.svg` and
|
|
`telem-dark.svg`
|
|
- source: `scripts/ingest-app-definitions.mjs` (`specialMethodsFor`, slug
|
|
`telem`) and `packages/shared/src/self-serve-mcp-research.json`
|