Agent-Hellboy / Agent-Hellboy/mcp-runtime

Docs: implementation-side MCP operational reference

Offen
#292 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
documentation
Vorherrschende Sprache
Go
Sterne
6
Forks
1
Ø Merge
11 Std. 33 Min.
Gemergte PRs (30 T.)
13

Beschreibung

## Problem

The MCP protocol spec describes the wire format well, but the operational envelope is undocumented. Implementers learn session lifecycle, transport behavior, auth propagation, and error surfaces the hard way — from logs and trial and error.

There is no structured reference for:
- Session lifecycle: when does a session invalidate, what happens to in-flight tool calls on disconnect, which errors are retriable vs fatal
- Transport behavior: differences between stdio, SSE, and HTTP transports in practice (connection state, reconnect semantics, backpressure)
- Tool registration: when tools are resolved, what happens on schema change between probes, how registration errors surface
- Auth propagation: how credentials flow from agent → gateway → MCP server, what fails silently vs loudly
- Error surfaces: full taxonomy of error codes, which layer produces each, and what the caller should do
- State across calls: what survives a session reconnect, what is per-call vs per-session vs per-server

## Proposed

Add a new reference section to `mcpruntime.org/docs/` (not the articles site — this is reference material, not narrative):

```
docs/mcp-implementation/
session-lifecycle.md — states, transitions, invalidation, in-flight behavior
transports.md — stdio vs SSE vs HTTP: semantics, reconnect, connection state
tool-registration.md — resolution timing, schema changes, registration errors
auth-propagation.md — credential flow, failure modes, silent vs loud errors
error-reference.md — full error taxonomy by layer and what callers should do
state-model.md — what is per-call / per-session / per-server, reconnect survival
```

Articles on `articles.mcpruntime.org` are the right place for narrative ("why we designed auth this way", "how we debugged a session leak") — this issue is specifically for the scannable reference docs that people reach for when stuck mid-implementation.

## Out of scope

- Protocol spec changes
- New features
- Articles / blog posts

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.