Agent-Hellboy / Agent-Hellboy/mcp-runtime
Docs: implementation-side MCP operational reference
- Lenguaje dominante
- Go
- Estrellas
- 6
- Forks
- 1
- Merge medio
- 11 h 33 min
- PR fusionados (30 d)
- 13
Descripción
## 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
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Evaluación
Este issue todavía no se ha evaluado.