reflect MCP server
2026년 11월 14일 커밋텔레메트리 캡처, 토큰 비용 측정, 자동화된 엔지니어링 워크플로우의 영향을 추적하여 AI 코딩 에이전트의 성능을 분석합니다.
다른 이름 o11y-dev/reflect
- 스타
- 20
- Tools
- 5
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- Apache-2.0
reflect MCP란?
텔레메트리 캡처, 토큰 비용 측정, 자동화된 엔지니어링 워크플로우의 영향을 추적하여 AI 코딩 에이전트의 성능을 분석합니다. 5개 도구를 제공합니다. 예: reflect_context, reflect_record_milestone, reflect_complete.
프로젝트 README에서 생성된 요약
reflect MCP server 정보
Reflect는 엔지니어링 팀이 텔레메트리와 비용 측정을 통해 AI 코딩 에이전트의 성능을 분석할 수 있도록 지원합니다. 세션 데이터를 캡처하고, 반복되는 엔지니어링 절차를 발견하며, 자동화된 워크플로우가 실제 미래 작업 결과에 개선을 가져오는지 추적하는 로컬 우선 개선 루프로 작동합니다. 로컬 우선 방식이므로 모든 텔레메트리, 작업 증거, SQLite 상태는 호스팅된 백엔드나 Reflect 계정 없이 사용자의 기기에 유지됩니다.
개발자는 CLI 또는 MCP server를 통해 도구를 사용하여 에이전트와 직접 상호작용할 수 있습니다. reflect doctor 명령어로 캡처 준비 상태를 진단하거나, reflect skills 명령어로 버전 관리된 절차의 로컬 레지스트리를 관리할 수 있습니다. 이 시스템은 Claude Code, Cursor, GitHub Copilot, Windsurf를 포함한 다양한 에이전트를 지원합니다. 로컬 주소에서 제공되는 시각적 대시보드를 통해 세션, 비용 및 설치된 워크플로우의 영향을 탐색할 수 있습니다. 설정은 로컬 OTLP 게이트웨이를 구성하고 reflect-mcp server를 등록하는 단일 명령으로 완료됩니다.
활용 사례
- 1세션 비용 분석에이전트에게 특정 코딩 세션의 비용이 많이 발생한 이유를 설명하도록 요청하고 개선이 필요한 부분을 식별합니다.
- 2재사용 가능한 절차 식별에이전트 로그 내에서 재사용 가능한 워크플로우로 변환하기 적합한 반복적인 엔지니어링 패턴을 찾습니다.
- 3AI 예산 증액 근거 마련측정된 작업량과 실제 토큰 사용 데이터를 기반으로 더 많은 AI 리소스를 요청하기 위한 근거를 생성합니다.
- 4워크플로우 효과 검증새로 설치된 자동화 워크플로우가 유사한 작업의 결과를 실제로 개선했는지 확인합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
reflect MCP 도구 5
README에서 감지됨reflect_contextreflect_record_milestonereflect_completereflect_review_changereflect_apply_change
| reflect_context | — | |
| reflect_record_milestone | — | |
| reflect_complete | — | |
| reflect_review_change | — | |
| reflect_apply_change | — |
구성
REFLECT_OTLP_MAX_BYTESREFLECT_OTLP_SEGMENT_BYTESREFLECT_REFRESH_INTERVAL_SECONDS
| 이름 | 설명 | 유형 |
|---|---|---|
| REFLECT_OTLP_MAX_BYTES | — | |
| REFLECT_OTLP_SEGMENT_BYTES | — | |
| REFLECT_REFRESH_INTERVAL_SECONDS | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능o11y-dev/reflect is public and reachablegithub.com/o11y-dev/reflect ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-10github.com/o11y-dev/reflect ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음5 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Reflect 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
reflect MCP 질문
reflect MCP는 어떤 도구를 제공하나요?
5개 도구를 제공합니다. 예: reflect_context, reflect_record_milestone, reflect_complete, reflect_review_change, reflect_apply_change.
Reflect를 사용하려면 클라우드 계정이나 호스팅된 백엔드가 필요한가요?
아니요, Reflect는 로컬 우선(local-first) 방식입니다. 모든 텔레메트리와 상태가 사용자의 기기에 남으므로 호스팅된 백엔드나 Reflect 계정이 필요하지 않습니다.
지원되는 운영 체제는 무엇인가요?
Reflect는 macOS와 Linux를 지원하며 Python 3.12 이상이 필요합니다.
Reflect는 데이터 프라이버시와 텍스트 캡처를 어떻게 처리하나요?
프롬프트 및 응답 텍스트 캡처는 선택 사항이며, 설정 시 메타데이터 전용, 마스킹된 텍스트, 전체 텍스트 모드를 제공합니다.
Reflect가 제 워크플로우를 자동으로 변경할 수 있나요?
아니요, 증거를 검토하고 리뷰를 준비할 수는 있지만, 사용자의 명시적인 승인 없이 워크플로우를 설치하거나 변경할 수 없습니다.