reflect MCPサーバー
コミット 2026年11月14日テレメトリの取得、トークンコストの測定、自動化されたエンジニアリングワークフローの影響を追跡することで、AIコーディングエージェントのパフォーマンスを分析します。
別名 o11y-dev/reflect
- スター
- 20
- ツール
- 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はローカルファーストです。すべてのテレメトリと状態はマシン内に保持されるため、ホストされたバックエンドやReflectアカウントは必要ありません。
サポートされているOSは何ですか?
ReflectはmacOSとLinuxをサポートしており、Python 3.12以上が必要です。
Reflectはデータのプライバシーとテキストのキャプチャをどのように処理しますか?
プロンプトとレスポンスのテキストキャプチャはオプトイン方式です。セットアップ時に、メタデータのみ、マスクされたテキスト、フルテキストのモードを選択できます。
Reflectがワークフローを自動的に変更することはありますか?
いいえ。エビデンスの調査やレビューの準備はできますが、人間の明示的な承認なしにワークフローをインストールしたり変更したりすることはありません。