Agent-Hellboy / Agent-Hellboy/mcp-runtime

Docs: implementation-side MCP operational reference

Aperta
#292 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
documentation
Lingua principale
Go
Stelle
6
Fork
1
Merge medio
11h 33m
PR unite (30g)
13

Descrizione

## 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

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.