convez.ai
MCP ServerIntegração & APIsIntermediário
zzstoatzz

Semble API — Cliente Python para Curação de Conhecimento

zzstoatzz/semble

SDK + MCP para curação colaborativa de conhecimento no ATProto

Ver no GitHub
InicialPluginScore · de 0 a 100

SDK Python tipado com CLI e servidor MCP para Semble, plataforma de bookmarking colaborativo e curação de conhecimento construída sobre ATProto. Oferece clientes síncronos e assíncronos para gerenciar cards (URLs), coleções, buscas semânticas e feeds em uma rede descentralizada.

Instalação

$npx convez-ai zzstoatzz/semble

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar Semble em aplicações Python para gerenciar bibliotecas de URLs e anotações
  • Buscar semântica em conhecimento pessoal e da rede Semble
  • Automatizar workflows de curação, conexões entre URLs e feed management
  • Expor funcionalidade Semble via MCP server para Claude e outros agentes

Veredito

Integração técnica bem estruturada para ecossistema ATProto, com SDK Python robusto (pydantic + httpx2) e suporte MCP. Ideal para quem quer automatizar curação de conhecimento ou construir features sobre Semble em aplicações Python.

README

A tradução para o português deste README ainda está na fila.

semble-api

python client for the semble api — collaborative bookmarking and knowledge curation on atproto.

built on httpx2 and pydantic, with sync and async clients.

installation

uv add semble-api

quick start

create an api key at semble.so/settings/api-keys, then:

from semble import Semble

client = Semble()  # reads SEMBLE_API_KEY from the environment or a local .env

# add a url to your library
result = client.cards.add_url("https://example.com", note="worth a read")

# search your cards
for card in client.cards.search("durable execution"):
    print(card.url)

# semantic search across semble
for hit in client.search.semantic("agent memory", threshold=0.7):
    print(hit.metadata.title, hit.url)

async is the same surface:

from semble import AsyncSemble

async with AsyncSemble() as client:
    profile = await client.actors.get_my_profile(include_stats=True)
    feed = await client.feeds.get_following(limit=25)

api surface

resources mirror the network.cosmik.* xrpc namespaces:

namespacewhat's there
client.cardsadd/search/list urls and notes, metadata, library status
client.collectionscreate/update/delete collections, followers, contributors
client.connectionstyped links between urls (supports, opposes, explains, ...)
client.feedsglobal and following activity feeds
client.notificationslist, unread count, mark read
client.searchsemantic search, similar urls, account search
client.actorsprofiles
client.graphfollow/unfollow users and collections

every endpoint not yet wrapped is reachable via the escape hatch:

client.get("network.cosmik.card.getLibraryStatus", {"url": "https://example.com"})

semble.records has pydantic models for the raw network.cosmik.* pds records, if you're reading or writing them directly (e.g. with pdsx).

configuration

settings come from explicit kwargs, then SEMBLE_* environment variables, then a local .env file (via pydantic-settings):

settingkwargdefault
SEMBLE_API_KEYapi_keyunauthenticated (public reads work)
SEMBLE_BASE_URLbase_urlhttps://api.semble.so/xrpc
SEMBLE_TIMEOUTtimeout30.0

the api key is held as a pydantic SecretStr, so it won't leak into logs or reprs.

cli

a small cyclopts cli ships as an extra:

uv add 'semble-api[cli]'
# or run without installing
uvx --from 'semble-api[cli]' semble --help

semble whoami                          # auth sanity check
semble feed 10 --following             # activity feeds
semble search "durable execution"      # semantic search
semble library pdewey.com              # anyone's library (or yours, with no handle)
semble add https://example.com --note "worth a read"
semble rm <card-id>

output is machine-readable by default — lists are ndjson, single results are one json object, keys match the api's camelCase — so it pipes straight into jq or an agent. add --pretty to any command for human-formatted output:

semble feed 25 | jq -r '.card.url'
semble search "agent memory" | jq -r '.metadata.title'
semble feed --pretty

mcp server

the mcp extra ships a semble-mcp entry point that exposes this sdk to mcp clients via fastmcp code mode: three meta-tools (search / get_schema / execute) instead of one tool per endpoint, with model-written python composing sdk calls in a monty sandbox. intermediate results stay in the sandbox; only the final answer returns to the model's context.

create an api key at semble.so/settings/api-keys, then:

claude mcp add semble -e SEMBLE_API_KEY=your-key -- uvx --from 'semble-api[mcp]' semble-mcp

for other mcp clients (claude desktop, cursor, ...), the equivalent json config:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble-api[mcp]", "semble-mcp"],
      "env": { "SEMBLE_API_KEY": "your-key" }
    }
  }
}

the key is optional — without it the server is limited to public reads. the server also picks up SEMBLE_API_KEY from the environment or a .env in the working directory, so inside a checkout of this repo a plain claude mcp add semble -- uv run --directory /path/to/this/repo semble-mcp works too.

hosted (http) deployments resolve auth per request instead: send your key as an x-semble-api-key header and it's used only for the calls that request triggers — one shared server url serves many users without holding anyone's identity. no header means public reads. a hosted instance runs at https://semble.fastmcp.app/mcp:

claude mcp add semble --transport http https://semble.fastmcp.app/mcp -H "x-semble-api-key: your-key"

requirements.horizon.txt exists for hosting platforms whose builders can't install extras from pyproject.toml.

examples

scripts/roundtrip.py exercises the write paths end to end (add url → note → collection → cleanup). it mutates your real account, so run it deliberately:

uv run scripts/roundtrip.py

development

just test   # pytest
just fmt    # ruff format + check
just check  # ty

see also

Ver o original no GitHub

Bom para

Relacionados