# Bowire — full reference for LLMs

> The API workbench that embeds in your own service. Auto-discovers gRPC, REST/OpenAPI, GraphQL, SignalR, WebSocket, SSE, MQTT, NATS, Pulsar, JSON-RPC, SOAP, Socket.IO, OData, MCP, and OTLP services from a running endpoint and gives you a single browser UI to inspect schemas, call methods, stream messages, receive telemetry, mock backends, record/replay sessions, and assert on responses. Ships embedded as ASP.NET middleware (`MapBowire()`) or as a standalone .NET tool / container.

This file is the verbose, AI-readable companion to `llms.txt`. It contains install commands, code snippets, the API surface, and answers to the most common questions in one self-contained document so an agent doesn't need to crawl the site to understand Bowire.

License: Apache-2.0. Source: https://github.com/Kuestenlogik/Bowire. Brand: Küstenlogik (https://kuestenlogik.com), Northern Germany.

## What problem Bowire solves

Modern .NET services rarely speak only HTTP+JSON. A single product can ship gRPC for backend-to-backend, REST for the web frontend, SignalR for live updates, MQTT or NATS for IoT integration, Kafka or Pulsar for event streams, GraphQL for partner APIs, MCP for AI-agent access, and emit OTLP traces / metrics / logs for observability. Each protocol traditionally needs its own debugging tool — Postman for REST, grpcurl for gRPC, MQTT Explorer for MQTT, an OTLP collector for telemetry, Insomnia for GraphQL — and each tool re-asks the developer for the same metadata (services, methods, schemas, headers, auth).

Bowire auto-discovers all of these from one running endpoint URL and renders them in one workbench. You point Bowire at `https://api.example.com` (or `app.MapBowire()` inside your own ASP.NET service) and get every callable method across every supported protocol, with the same UI for unary calls, server-streaming, client-streaming, and duplex channels.

## Install paths

```bash
# Standalone CLI / .NET global tool — runs from anywhere
dotnet tool install -g Kuestenlogik.Bowire.Tool

# Embedded — middleware inside your own ASP.NET service (recommended)
dotnet add package Kuestenlogik.Bowire

# Container
docker pull kuestenlogik/bowire:0.9.4

# Native installers (pre-built archives + winget / brew)
winget install Kuestenlogik.Bowire.Tool
brew install kuestenlogik/tap/bowire
```

All packages are at https://www.nuget.org/profiles/Kuestenlogik. Source-link is wired up so consumers can step into Bowire source from any debugger.

## Embedded mode — the two-line integration

```csharp
using Kuestenlogik.Bowire;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddBowire();          // protocol plugins auto-discovered
var app = builder.Build();
app.MapBowire();                       // workbench at /bowire
app.Run();
```

Visit `http://localhost:5000/bowire`. Bowire scans the live `IServiceProvider` for `IBowireProtocol` implementations and `EndpointDataSource` for app routes, so all your services, hubs, and OpenAPI endpoints are listed without any manual registration.

## Standalone mode — point at any URL

```bash
bowire                                          # opens the UI on localhost:5080
bowire list https://api.example.com             # discover services
bowire describe ServiceName.MethodName          # show signature
bowire call ServiceName.MethodName --json '...' # invoke
bowire mock --recording session.har             # replay as a local server
bowire mcp serve                                # expose discovered methods as MCP tools
```

## Protocol plugins (one NuGet package each)

Built-ins ship in the Bowire core repo:

- `Kuestenlogik.Bowire.Protocol.Rest` — OpenAPI / Swagger discovery, AWS Sig v4
- `Kuestenlogik.Bowire.Protocol.Grpc` — Server Reflection, all four streaming types
- `Kuestenlogik.Bowire.Protocol.GraphQL` — `__schema` introspection, subscriptions
- `Kuestenlogik.Bowire.Protocol.SignalR` — hub auto-discovery via `EndpointDataSource`
- `Kuestenlogik.Bowire.Protocol.WebSocket` — endpoint scan + duplex channel UI
- `Kuestenlogik.Bowire.Protocol.Sse` — Server-Sent Events with reconnect
- `Kuestenlogik.Bowire.Protocol.Mqtt` — broker connect, topic browse, publish/subscribe
- `Kuestenlogik.Bowire.Protocol.SocketIo` — Socket.IO 4.x event discovery
- `Kuestenlogik.Bowire.Protocol.OData` — `$metadata` discovery, entity sets
- `Kuestenlogik.Bowire.Protocol.Mcp` — Model Context Protocol both directions
- `Kuestenlogik.Bowire.Protocol.Nats` — pub/sub, JetStream streams, Services API + queue groups (NATS.Net 2.x)
- `Kuestenlogik.Bowire.Protocol.Soap` — WSDL 1.1 discovery, SOAP 1.1 + 1.2 envelopes, automatic Fault detection (no WCF)
- `Kuestenlogik.Bowire.Protocol.JsonRpc` — JSON-RPC 2.0 over HTTP with OpenRPC `rpc.discover`
- `Kuestenlogik.Bowire.Protocol.Pulsar` — Pulsar topic discovery + produce/subscribe via DotPulsar 3.5.x
- `Kuestenlogik.Bowire.Protocol.Otlp` — OpenTelemetry Protocol **passive listener**: SUTs export traces / metrics / logs via `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:<port>`; each received envelope surfaces channel-style for inspection. Phase 1 captures JSON content-types decoded + protobuf as base64 (Phase 2 inlines a decode via vendored opentelemetry-proto descriptors).

Sister-repo plugins:

- `Kuestenlogik.Bowire.Protocol.Udp` — generic UDP listener (multicast / broadcast / unicast)
- `Kuestenlogik.Bowire.Protocol.Dis` — IEEE 1278.1 DIS with typed PDU decode
- `Kuestenlogik.Bowire.Protocol.Kafka` — Apache Kafka via Confluent.Kafka, schema registry
- `Kuestenlogik.Bowire.Protocol.Amqp` — AMQP 0.9.1 + 1.0 via URL scheme (RabbitMQ-tested)
- `Kuestenlogik.Bowire.Protocol.TacticalApi` — Rheinmetall situational-awareness gRPC
- `Kuestenlogik.Bowire.Protocol.Akka` — Akka.NET remote actors
- `Kuestenlogik.Bowire.Protocol.Surgewave` — Küstenlogik Surgewave distribution-fabric tap (native wire + Kafka-compat mode)

## Writing your own plugin

Two paths — pick by language:

**1. .NET plugin (one NuGet package):**

```bash
dotnet new bowire-plugin -n Contoso.Bowire.Protocol.Foo --Preset rest
```

Implement `IBowireProtocol` (Name / Id / IconSvg / DiscoverAsync / InvokeAsync / InvokeStreamAsync / OpenChannelAsync) and `IBowireChannel` for duplex protocols. Tag your published nupkg with `<PackageTags>bowire bowire-plugin</PackageTags>` so it surfaces on https://github.com/topics/bowire-plugin.

**2. Polyglot sidecar (any language):**

Plugins that don't run on .NET ship as a sidecar process speaking JSON-RPC 2.0 over **stdio (NDJSON)** or **HTTP + SSE** — same dual-transport story as MCP. Bundle the executable + a `sidecar.json` manifest into a zip and install with `bowire plugin install --file`, accepting a local path, an `http(s)://` URL, or an OCI registry ref:

```bash
bowire plugin install --file ./my-sidecar.zip
bowire plugin install --file oci://ghcr.io/acme/zenoh-sidecar:1.0.0
```

The Python SDK is out — `pip install bowire-plugin`, subclass `BowirePlugin`, call `run()` (stdio) or `run_http(plugin, host, port)` (HTTP/SSE). Node, Go, and Rust SDKs are on the roadmap.

Wire contract + manifest schema: https://bowire.io/docs/architecture/sidecar-plugins.html
Python SDK repo: https://github.com/Kuestenlogik/Bowire.Sdk.Python

## Mock server, recording, replay

Every Bowire session can be recorded — pure UI button — into a HAR-like JSON file. Recordings replay through:

- `bowire mock --recording session.har` — local HTTP server serving recorded responses
- Schema-only mocks: `--schema openapi.json` or `--grpc-schema service.proto` or `--graphql-schema schema.graphql` — generates plausible responses from the schema, no recording needed
- HTML CI report — pass/fail summary with collapsible step details

Mocks support chaos injection (latency, error injection), stateful cursors (CRUD-style), and capture-on-miss (when a request comes in that isn't in the recording, capture it from the live backend and add it).

**Mock as stand-in for the real service (v1.7+).** Recordings now carry the **original** source schema the discovery fetched (REST: the verbatim OpenAPI doc, AsyncAPI: the loader's normalised YAML, gRPC: the proto `FileDescriptorSet` per step). The mock serves the schema back at conventional URLs:

- `GET /openapi.json` / `/openapi.yaml` / `/swagger.json` — REST mocks
- `GET /asyncapi.yaml` / `/asyncapi.json` — messaging mocks
- gRPC ServerReflection — built-in for gRPC mocks

So a peer Bowire (or Swagger UI, AsyncAPI Studio, codegen tooling) pointed at the mock discovers the *full* declared surface, not just the recorded slice. Population is automatic — the workbench's recording-save path (`PUT /api/recordings`) auto-stamps `recording.sourceSchema` from a process-wide `SourceSchemaCache` the wire plugins populate at `DiscoverAsync` time. No user action needed.

## Schema export — `bowire export`

Inverse of the mock's schema-serve: turn a live discovery result back into a portable schema artefact. Two subcommands:

- `bowire export openapi <http-url> [--output api.yaml] [--recording session.bwr]` — REST → OpenAPI 3.0
- `bowire export asyncapi <wire-url> [--output api.yaml] [--recording session.bwr]` — messaging → AsyncAPI 3.0. URL scheme picks the wire plugin (`mqtt://`, `nats://`, `kafka://`, `ws://`, `amqp://`, `pulsar://`, `http://`).

When `--recording` is supplied, every operation in the emitted document gets an `x-bowire-coverage: { recorded, stepCount }` extension so consumers can see which slice of the contract this recording can replay deterministically vs. which slice would fall back to schema-generated samples. Default output is YAML on stdout; `--format json` switches to JSON.

## MCP integration (AI agents)

Two complementary modes via `Kuestenlogik.Bowire.Protocol.Mcp`:

- **Bowire as MCP server** — every method Bowire has discovered becomes an MCP tool exposed to Claude Desktop, Cursor, Copilot, etc. Plus tools for `discover` / `invoke` / `subscribe` / recording management. AI agents can drive Bowire from their conversation.
- **Bowire as MCP client** — connect to remote MCP servers, browse their tools / resources / prompts, and invoke them with the same UI as gRPC.

```bash
bowire mcp serve                  # MCP server over streamable-HTTP
bowire mcp connect mcp://remote   # MCP client browsing
```

## Architecture in three layers

1. `Kuestenlogik.Bowire` — UI shell (single-page HTML, inlined CSS/JS), plugin host, contracts (`IBowireProtocol`, `IBowireChannel`, `IBowireMockEmitter`), models (`BowireServiceInfo`, `BowireMethodInfo`, `BowireMessageInfo`, `InvokeResult`).
2. `Kuestenlogik.Bowire.Protocol.*` — one nupkg per protocol, each implementing `IBowireProtocol`. Loaded out of the consumer's bin directory or `~/.bowire/plugins/`.
3. `Kuestenlogik.Bowire.Mock` — separate package for recording/replay infrastructure. Plugins contribute `IBowireMockSchemaSource` for schema-only mocks and `IBowireMockTransportHost` for non-HTTP protocols (MQTT, WebSocket, etc.).

The whole pipeline (discovery → invoke → record → replay → assert) is plugin-extensible at every step.

## Common questions

**Q: Does Bowire phone home / send data anywhere?**
A: No. There is no telemetry, no cloud account, no proxy. Embedded mode runs fully in-process; standalone mode only talks to the URL you give it.

**Q: Is it free?**
A: Yes — Apache-2.0 source, MIT-style permissive use, including commercial.

**Q: Why .NET only?**
A: Bowire embeds via ASP.NET middleware. The CLI talks to any HTTP/gRPC/MQTT/etc. service regardless of the server's language — Bowire.Tool against a Java gRPC service works fine. Only the embedding (`AddBowire()` + `MapBowire()`) is .NET-specific.

**Q: How is it different from Postman / Insomnia / Bruno / Hoppscotch?**
A: Those are HTTP-first clients. Bowire starts with multi-protocol auto-discovery (no manual collection authoring), supports embedded mode (lives next to your service), records sessions to replay them as mock servers, and exposes everything as MCP tools for AI agents. The single-tool-many-protocols story plus embed-mode are the two main differentiators.

**Q: What's the relationship to Surgewave?**
A: Surgewave is Küstenlogik's separate distribution-fabric product. `Kuestenlogik.Bowire.Protocol.Surgewave` is an optional plugin that lets Bowire tap Surgewave event streams. Surgewave itself is not yet public.

**Q: Where do I report bugs / request features?**
A: https://github.com/Kuestenlogik/Bowire/issues for the core. Per-plugin sister repos have their own issue trackers.

## Map of resources

- Site: https://bowire.io/
- Docs: https://bowire.io/docs/
- Quickstart: https://bowire.io/quickstart.html
- Custom-protocol guide: https://bowire.io/docs/protocols/custom.html
- API reference: https://bowire.io/docs/api/Kuestenlogik.Bowire.html
- Source (core): https://github.com/Kuestenlogik/Bowire
- Source (plugin templates): https://github.com/Kuestenlogik/Bowire.Templates
- Source (samples): https://github.com/Kuestenlogik/Bowire.Samples
- NuGet profile: https://www.nuget.org/profiles/Kuestenlogik
- Roadmap: https://github.com/Kuestenlogik/Bowire/blob/main/ROADMAP.md
- Changelog: https://github.com/Kuestenlogik/Bowire/blob/main/CHANGELOG.md