MCP server de reflect
Commit 14 nov 2026Analiza el rendimiento de los agentes de codificación con IA capturando telemetría, midiendo costos de tokens y rastreando el impacto de los flujos de trabajo de ingeniería automatizados.
También conocido como o11y-dev/reflect
- Stars
- 20
- Herramientas
- 5
- Descargas, 30 días
- —
- Última versión
- —
- Último commit
- 14 nov 2026
- Licencia
- Apache-2.0
¿Qué es reflect MCP?
Analiza el rendimiento de los agentes de codificación con IA capturando telemetría, midiendo costos de tokens y rastreando el impacto de los flujos de trabajo de ingeniería automatizados. Expone 5 herramientas, como reflect_context, reflect_record_milestone, reflect_complete.
Resumen generado a partir del README del proyecto
Acerca del MCP server de reflect
Reflect permite a los equipos de ingeniería analizar el rendimiento de los agentes de codificación con IA mediante telemetría y medición de costos. Funciona como un ciclo de mejora local-first que captura datos de sesiones, descubre procedimientos de ingeniería repetitivos y rastrea si los flujos de trabajo automatizados realmente mejoran los resultados de tareas futuras. Al ser local-first, toda la telemetría, la evidencia de las tareas y el estado de SQLite permanecen en tu máquina sin necesidad de un backend alojado o una cuenta de Reflect.
Los desarrolladores utilizan la herramienta a través de una CLI o un MCP server para interactuar directamente con sus agentes. Puedes usar comandos como reflect doctor para diagnosticar la preparación de la captura o reflect skills para gestionar el registro local de procedimientos versionados. El sistema es compatible con varios agentes, incluyendo Claude Code, Cursor, GitHub Copilot y Windsurf. Proporciona un dashboard visual en una dirección local para explorar sesiones, costos y el impacto de los flujos de trabajo instalados. La configuración se realiza mediante un único comando que configura el gateway OTLP local y registra el reflect-mcp server.
Qué puedes hacer con él
- 1Analizar costos de sesiónPide a tu agente que explique por qué una sesión de codificación específica fue costosa e identifica áreas de mejora.
- 2Identificar procedimientos reutilizablesEncuentra patrones de ingeniería repetitivos dentro de los logs de tu agente que sean adecuados para convertirse en flujos de trabajo reutilizables.
- 3Justificar aumentos de presupuesto de IAGenera una solicitud para obtener más recursos de IA basada en el trabajo medido y los datos reales de uso de tokens.
- 4Verificar la efectividad de los flujos de trabajoDetermina si un flujo de trabajo automatizado recién instalado ha mejorado realmente los resultados de tareas comparables.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Herramientas de reflect MCP 5
Detectado desde el READMEreflect_contextreflect_record_milestonereflect_completereflect_review_changereflect_apply_change
| reflect_context | — | |
| reflect_record_milestone | — | |
| reflect_complete | — | |
| reflect_review_change | — | |
| reflect_apply_change | — |
Configuración
REFLECT_OTLP_MAX_BYTESREFLECT_OTLP_SEGMENT_BYTESREFLECT_REFRESH_INTERVAL_SECONDS
| Nombre | Descripción | Tipo |
|---|---|---|
| REFLECT_OTLP_MAX_BYTES | — | |
| REFLECT_OTLP_SEGMENT_BYTES | — | |
| REFLECT_REFRESH_INTERVAL_SECONDS | — |
Verificaciones automáticas
Ejecutado 14 nov 2026Informe completo →Aún no verificado. Un servidor necesita una puntuación de 80, ningún hallazgo grave y suficientes datos para que podamos revisarlo. Cómo funcionan las verificaciones · Qué corregir para obtener más puntos
- Repositorio de origen vinculado y accesibleo11y-dev/reflect is public and reachablegithub.com/o11y-dev/reflect ↗Aprobado
- El paquete indica este repositorio como su origenNo verificado
- Procedencia de la compilación (atestación de Sigstore)No verificado
- Licencia de código abierto (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Aprobado
- Commit o lanzamiento en el último añoLast commit or release 2026-11-10github.com/o11y-dev/reflect ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo verificado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
- Sin instrucciones ocultas para el modelo5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo tool named like delete, drop or execAprobado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHubReflect is a local-first improvement loop for AI coding agents. It captures what happened, discovers repeated engineering procedures, lets a developer review a bounded workflow, and measures whether comparable future tasks improved.
No hosted backend and no Reflect account are required. Telemetry, task evidence, workflow reviews, and SQLite state remain on your machine.
Quick Start
Reflect requires Python 3.12+. The supported operating systems are macOS and Linux. Review the public install script, then install and configure Reflect with one command:
curl -fsSL https://reflect.o11y.dev/install.sh | sh
reflect doctor
reflect
For a fresh installation, the script uses an available package manager in this
order: pipx, uv, then Python's pip in an isolated environment. It never uses
sudo or changes the system Python. It runs reflect setup after installation;
in a terminal you choose the integrations and text-capture mode, while
non-interactive use defaults to all detected agents with metadata-only capture.
Re-run the same command to update Reflect. The script detects whether the active installation belongs to pipx, uv, or pip, upgrades it with that owner, and preserves the existing setup.
Prefer manual installation?
pipx install o11y-reflect
# or: uv tool install o11y-reflect
reflect setup
reflect setup starts the local OTLP gateway, registers reflect-mcp, and
installs the packaged Reflect skills. On macOS it can register the gateway and
report server for login startup; pass --no-autostart to opt out.
reflect doctor is the source of truth for capture readiness. It distinguishes
configuration from an observed event, an ingested session, and reconciled
logical calls.
Ask through your agent
Use Reflect in the agent where the work is already happening:
Use Reflect to explain why this session was expensive and what should improve.
Use Reflect to find a repeated engineering procedure worth making reusable.
Use Reflect to prepare an internal AI budget increase request from measured work.
Use Reflect to show whether an installed workflow improved comparable tasks.
The packaged skill starts a non-trivial repository task with
reflect_context, keeps selected guidance tied to a task run, and closes it
with reflect_complete after validation. It can inspect evidence and prepare a
review, but it cannot install or change a workflow without explicit human
approval.
Explore visually in the UI
reflect
The browser opens at http://127.0.0.1:8765. It reads the same local SQLite
evidence as the CLI and MCP server. The normal refresh-enabled server prepares
new telemetry immediately and every five minutes; reflect server start is
snapshot-only unless --refresh is supplied.
No data yet? Open the bundled cross-agent demonstration:
reflect --demo
The demo contains Claude, Codex, Copilot, Cursor, and historical Gemini sessions. Demo coverage is not a claim that every provider surface is currently live-supported.
From Personal Reflection to Organizational Improvement
The product loop is:
task contract -> execution evidence -> human review -> installed workflow -> comparable future tasks -> measured impact
The browser has six surfaces:
| Surface | What it answers |
|---|---|
| Sessions | What happened, what did it cost, and which source evidence is available? |
| Inbox | Which findings and repeated behaviors need investigation before becoming interventions? |
| Workflows | Which bounded intervention contracts need review, installation, or rollback? |
| Skills | Which versioned procedures exist, where are they installed, and have agents used them? |
| Impact | Did comparable task outcomes move after installation, and is attribution supported? |
| Explore | What do usage, tools, MCP, graph, context, and task contracts show? |
A finding or loop is evidence, not an installed improvement. Approval and installation are separate. Impact begins only after a workflow is installed, and missing baseline evidence is shown as unavailable rather than zero.
Skills Registry
Skills are durable, versioned procedures—not another label for findings or
workflow drafts. The Skills surface shows registry state, installation targets,
source evidence, observed exposure, and measured outcomes without implying that
a registered skill is installed or effective. Use reflect skills or
reflect_skills for the same local registry through the CLI or MCP.
What Reflect Can Prove
Reflect derives these views from canonical local evidence:
- session conversations, outcomes, duration, agents, and source provenance
- exact or explicitly estimated tokens and cost, with model and cache breakdowns
- one logical count per tool or MCP invocation
- failures, retries, recovery, verification, edits, and delegation
- bounded task executions and comparable task archetypes
- workflow contract adherence before and after installation
- measured outcome shifts and the evidence quality required for attribution
Reflect does not rank developers or agents. It does not combine unrelated task types, treat an entire long-lived session as one task, or convert correlation into causality.
Trust and Privacy Contract
- Local traces, logs, native session data, and
reflect.dbstay under local state paths and supported agent-owned stores. - Prompt and response text capture is opt-in. Setup offers metadata-only, masked-text, and full-text modes.
- Normalized evidence keeps source provenance and marks token/cost estimates.
- External or repository writes require exact preview and explicit approval; apply and rollback are separate recorded actions.
- Workflow impact exposes compared task IDs, cohort size, missing telemetry, evidence cutoff, and the reason a claim is withheld.
- Retention can remove telemetry without silently installing, applying, or changing reviewed workflows.
For non-interactive setup, choose capture explicitly:
reflect setup --text-capture-mode metadata
Project-local agent wiring is opt-in:
reflect setup --agent "Claude Code" --local-agent "Claude Code"
Agent Capability Truth
Support is declared per surface. A working MCP connection does not prove native tokens, cost, hooks, or transcripts.
| Agent | Status | Current evidence path |
|---|---|---|
| Claude Code | Supported | Native OTel + hooks + native sessions |
| Cursor | Supported | Session/log adapters + optional hooks |
| Antigravity | Partial | Reflect MCP task runs; native tool telemetry unverified |
| GitHub Copilot | Supported | Native OTel + hooks + native sessions |
| OpenAI Codex CLI | Supported | Native OTel + native sessions |
| OpenCode | Supported | Native SQLite sessions + hooks |
| Windsurf | Supported | Hooks + configuration snapshots |
| Gemini CLI | Historical | Historical native OTel + session adapter |
Planned agents may be inventoried for configuration or skill paths, but Reflect does not label them as capturing.
Antigravity's current CLI alias is agy; Windsurf MCP setup is editor-config only.
The registry in src/reflect/agent_capabilities.py feeds setup, doctor, aliases,
skill distribution, MCP configuration, and local-agent tests.
How Capture Works
flowchart LR
A[Native OTel and hooks] --> B[Bounded raw JSONL segments]
C[Agent-native stores] --> D[Checkpointed ingestion]
B --> D
D --> E[Canonical normalization]
E --> F[(Local SQLite)]
F --> G[Sessions and Explore]
F --> H[Findings and workflows]
H --> I[Installed version]
I --> J[Comparable-task impact]
The gateway appends to otel-traces.active.jsonl and
otel-logs.active.jsonl, rotating immutable closed segments at a bounded size.
Refresh checkpoints each source, normalizes new records, and deletes only
closed segments whose events normalized successfully. Use
--keep-processed-raw when replay files must be retained.
The combined trace-and-log replay buffer has a 4 GiB hard admission limit by
default. At the limit the gateway preserves every existing byte and rejects new
HTTP telemetry with 507 or gRPC telemetry with RESOURCE_EXHAUSTED; it never
deletes unprocessed evidence to make room. The dashboard, reflect doctor, and
reflect gateway status warn at 80% and show when capture is paused. A
successful refresh removes eligible processed closed segments and capture then
resumes automatically.
Operators can override the positive byte and cadence values before starting the managed services:
REFLECT_OTLP_MAX_BYTES=4294967296 # combined raw traces + logs
REFLECT_OTLP_SEGMENT_BYTES=268435456 # one active segment
REFLECT_REFRESH_INTERVAL_SECONDS=300 # refresh-enabled report server
tool_calls stores one logical invocation. mcp_calls is a one-to-one metadata
extension for MCP server, tool, transport, and protocol identity, not a second
call ledger.
See the contribution guide for module ownership, data flow, and architectural guardrails.
Common Commands
reflect usage # current runtime usage
reflect usage --global --period week # all matching local usage for seven days
reflect refresh --json # explicit ingest and snapshot refresh
reflect improve # scoped findings
reflect loops # observed stalled or productive loops
reflect workflows list # reviewable and historical workflow state
reflect skills # durable skill registry
reflect memory sync . # sync scoped instruction memory
reflect doctor # capture and installation diagnostics
Read commands inspect an existing query-only snapshot. Commands that refresh, install, roll back, prune, or vacuum are explicit mutations.
Direct OTLP input
An explicit trace file remains supported for imports and tests:
reflect --otlp-traces path/to/otel-traces.json
If a sibling otel-logs.json exists, Reflect reads it as the corresponding log
source. The managed gateway uses the bounded .active.jsonl segment names.
Workflow and Impact Lifecycle
Reflect keeps these states separate:
- Evidence produces a finding or loop.
- A workflow candidate defines a typed procedure and validation window.
- The developer's human review approves an exact immutable revision.
- Explicit apply installs that version at one target.
- The next comparable task executions record exposure and adherence.
- Impact compares the frozen baseline with the bounded post-install cohort.
- The developer keeps, revises, or rolls back the installation.
An approved-but-uninstalled workflow is never selected as executable guidance. Workflow identity comes from contract semantics; a title or wording edit alone does not invent a new procedure.
Reflect MCP
reflect-mcp is a local stdio MCP server. Its main tools are:
reflect_context— start task-specific guidancereflect_record_milestone— record idempotent workflow checkpointsreflect_complete— close the task after validationreflect_improvements,reflect_patterns,reflect_skills, andreflect_impact— bounded read-only evidencereflect_explainandreflect_usage— provenance and exact usagereflect_review_change— return an exact diff, target, risks, and rollbackreflect_apply_change— consume only the explicitly approved exact review
Setup writes the appropriate client configuration for Claude, Cursor, Antigravity, Copilot, Codex, OpenCode, and Windsurf. Windsurf has no supported headless test surface. Historical Gemini telemetry parsing is independent of current Antigravity MCP configuration.
To verify one task lifecycle after capture:
reflect usage --session <session-id> --refresh --json
A task that called reflect_context and reflect_complete should show two
successful logical MCP calls once its runtime telemetry has been ingested.
Shell Completion
Setup leaves shell files unchanged by default. Review the exact target paths and managed block before an explicit Bash, Zsh, or Fish installation:
reflect completion --install
reflect setup --shell-completion
reflect completion --shell zsh
Development
Source development uses Poetry:
poetry install --extras test
poetry run reflect --demo
poetry run reflect doctor
poetry run pytest tests/test_dashboard_sql_api.py -q
poetry run pytest -q
The browser is authored in src/reflect/frontend/. Regenerate both shipped
single-file artifacts after client changes:
poetry run python scripts/build_dashboard.py
Before a release:
poetry run ruff check .
poetry run pytest -q --no-cov
poetry run python scripts/release_workflow.py release-notes 0.9.7
See CONTRIBUTING.md for architecture, development, and review conventions, and the analysis schema for canonical telemetry fields.
License
Preguntas sobre reflect MCP
¿Qué herramientas proporciona reflect MCP?
Expone 5 herramientas, incluidas reflect_context, reflect_record_milestone, reflect_complete, reflect_review_change, reflect_apply_change.
¿Requiere Reflect una cuenta en la nube o un backend alojado?
No, Reflect es local-first. No se requiere un backend alojado ni una cuenta de Reflect, ya que toda la telemetría y el estado permanecen en tu máquina.
¿Qué sistemas operativos son compatibles?
Reflect es compatible con macOS y Linux, y requiere Python 3.12 o superior.
¿Cómo gestiona Reflect la privacidad de los datos y la captura de texto?
La captura de texto de prompts y respuestas es opcional (opt-in), ofreciendo modos de solo metadatos, texto enmascarado y texto completo durante la configuración.
¿Puede Reflect cambiar mis flujos de trabajo automáticamente?
No, aunque puede inspeccionar evidencia y preparar revisiones, no puede instalar ni cambiar un flujo de trabajo sin la aprobación explícita de un humano.