convez.ai
MCP Server
thingctx

thingctx

thingctx/thingctx

Ver no GitHub
BomPluginScore · de 0 a 100

Drive any agent against any W3C WoT Thing from its description. No per-integration server.

Instalação

$npx convez-ai thingctx/thingctx

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
16
Forks
12
Acompanhando
2
Saúde
50%
Último commit
há 1 semana
Versão
v0.3.0
Issues abertas
37
Contribuidores
1

README

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

thingctx

One description, and your model reads from and acts on a real device, sensor, tool, or service, directly. No per-integration server.

thingctx.com: browse real services (GitHub, Stripe, Slack, and more) as ready-to-use Thing Descriptions.

thingctx uses the W3C Web of Things standard as a uniform interface between an AI app and the systems it reaches. Point it at a Thing Description and it drives the actual Thing the description names, over that Thing's own transport. The integration is a document, not a server you run.

A "Thing" is anything with a callable interface, not just hardware: a sensor or a robot, but equally a REST API, a database, a SaaS product, an internal service. A Thing Description (TD) is plain JSON that names that system's actions (things to do), properties (state to read or write), and events (things to subscribe to), plus the transport for each (HTTP, MQTT, local, and more). thingctx reads it, hands the actions to your model as tools, and calls each against the real system. The system's own endpoints are the server; you write nothing server-side.

A whole TD can be this small (a weather API, no hardware in sight):

{
  "@context": "https://www.w3.org/2022/wot/td/v1.1",
  "id": "urn:example:weather:v1",
  "title": "Weather",
  "securityDefinitions": { "bearer_sc": { "scheme": "bearer" } },
  "security": ["bearer_sc"],
  "properties": {
    "temperature": { "type": "number", "readOnly": true,
      "forms": [{ "href": "https://api.example.com/temp" }] }
  },
  "actions": {
    "forecast": {
      "input": { "type": "object", "properties": { "city": { "type": "string" } } },
      "forms": [{ "href": "https://api.example.com/forecast", "htv:methodName": "POST" }]
    }
  }
}

Point an agent at it:

import thingctx

host = await thingctx.from_url("https://api.example.com/.well-known/wot")
print(await host.chat("what's the forecast for Cairo, and the current temperature?"))

The model picks the actions; thingctx routes each to its transport.

Install

pip install thingctx[all]      # litellm + httpx + paho-mqtt + jsonschema + mcp
# or pick extras: thingctx[llm] [http] [mqtt] [validate] [mcp]

Drive it directly

Own the agent loop? Read a description, get the tool specs to hand your model, and route each call back to the Thing. Nothing in between.

import thingctx

client = thingctx.ThingClient.from_registry(
    thingctx.from_arg("http://device.local/.well-known/wot"))   # a URL, folder, or TDD
specs, invoke = client.as_tools()        # specs for your model; invoke(name, args) runs a call

await invoke("pump.set_speed", {"rpm": 1500})
await client.read_property("pump.rpm")

Add a Thing by pointing at one more description.

Reach a closed agent: the MCP bridge

Some agents are closed: you can't hand their model tools directly, only through MCP (Claude Desktop, the Claude CLI, Copilot). For those, thingctx ships one generic MCP server that turns a registry of descriptions (a folder, a URL, or a W3C Thing Description Directory) into MCP tools, with no per-integration server.

pip install "thingctx[mcp,http]"
thingctx-mcp ./examples/registry/        # a folder, a URL, or a TD Directory
{ "mcpServers": { "things": { "command": "thingctx-mcp",
  "args": ["./examples/registry/"] } } }

MCP is just one way to deliver the description, for agents where direct tool calling isn't available.

Why not MCP

MCP solves the wrong problem. Calling a real system from a model was always a tooling limitation, not a protocol one: read an interface, hand the model tool specs, route each call to its transport , all client-side, drivable from a plain description. MCP turns that gap into infrastructure you operate instead of data you read.

To expose a system over MCP you write a server, deploy it, and keep it running, one per integration. N systems means N processes to operate. A Thing Description is a static file: write it (or generate it), check it into git, or serve it from a URL. There is nothing to run, nothing to keep alive. Integration becomes data, not a service, and data scales to a fleet for free.

A messy device (binary protocol, a session dance) gets one thin connector that exposes a clean WoT face; the TD describes that. The connector is consumed the same way by an LLM, an MCP client, or anything else.

See examples/01_mcp_baseline.py (a server per integration) and examples/02_thingctx_baseline.py (no server). Both drive the same pump; every result is asserted equal to calling the system directly. The difference is what you build and run to get there:

per integrationMCP (stdio)MCP (http)thingctx
server processper session1, long-run0
hand-written lines14214210
time to first call540 ms13 ms2 ms

thingctx calls in milliseconds because there is no server to start. MCP needs one, and the transport sets the cost: stdio spawns it per session (the first call pays process startup, 540 ms), streamable-HTTP is a server you keep running and connect to (13 ms, warm). Once connected, per-call latency is small for all three; the difference is the server you build and run to get there. The Thing Description is data, about 145 lines of JSON, written once and read by every consumer. Reproduce with python examples/_measure.py.

Reference

ThingClient: the core

Stdlib only, with no dependency on any agent framework. ThingClient has no LLM and no opinion on what chose the action. It reads properties, writes them, and streams events, and routes each call to the transport the TD's form names, so one client can read over HTTP and subscribe over MQTT without you wiring either:

await client.read_property("pump.rpm")          # e.g. an HTTP GET
await client.write_property("pump.target_rpm", 1500)
async for evt in await client.subscribe("pump.overheat"):   # e.g. an MQTT topic
    ...                              # evt is the payload, e.g. {"temp": 98}

(thingctx.from_url(...) returns a ready LLMHost if you just want a loop out of the box.)

Registry

Where descriptions come from: a folder of files, a URL, or a Thing Description Directory (TDD). ThingClient, the MCP bridge, and the LLM loop all build from the same registry.

client = thingctx.ThingClient.from_registry(thingctx.from_arg("./examples/registry/"))

The hosted registry at thingctx.com is one such source.

The TDD is the W3C WoT Discovery standard (a final Recommendation): a service that serves a whole fleet of Things from a /things endpoint, with optional search. thingctx reads from any compliant TDD. Point from_arg at its URL.

Authentication

The TD declares the scheme (bearer, basic, apikey); the secret is supplied to the invoker at runtime, never in the TD, so a TD is safe to commit and share. Secrets are keyed by Thing id, then slug, then scheme name, so one client can carry a different secret per Thing.

thingctx.HttpInvoker(credentials={"weather": "secret"})  # by Thing id/slug, or scheme name

License

Apache-2.0. Copyright 2026 The thingctx Authors.

Ver o original no GitHub

Bom para

Relacionados