Agent-Hellboy / Agent-Hellboy/mcp-runtime

Docs: implementation-side MCP operational reference

Abierto
#292 0 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation
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.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.