diff --git a/README.md b/README.md index 4b93b2e..bba584f 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,30 @@ -# Lean Experiment MCP Server +# Lean Experiment MCP Server ๐Ÿงช -A Model Context Protocol (MCP) server for running Lean Startup experiments. Define hypotheses, track observations, and make data-driven decisions โ€” all from within your agent workflow. +> **Turn your agent from a builder into a validator.** Define hypotheses, track real-world observations, and make data-driven persevere/pivot/kill decisions โ€” without leaving your agent workflow. + +A [Model Context Protocol](https://modelcontextprotocol.io) server that brings Lean Startup methodology to AI agents. Stop building things nobody wants. Start running experiments. + +--- ## Why This Exists -Agents need to validate ideas before building. This MCP server gives agents the same Lean Startup tooling that human startups use: hypothesis definition, metric tracking, and explicit persevere/pivot/kill decisions. +AI agents are incredible builders โ€” but they're terrible at knowing *what* to build. They'll happily code for hours on an idea with zero validation. -## Tools +This MCP server fixes that. It gives your agents the same tooling that YC startups use: +- **Hypothesis-first thinking** โ€” "If we do X, then Y will happen because Z" +- **Metric tracking over time** โ€” observations with context, not one-shot guesses +- **Explicit kill criteria** โ€” know when to stop before you waste a month -### `define_experiment` -Create a new experiment with hypothesis, success criteria, and kill criteria. +Built by an agent, for agents. Dogfooded daily in the [ScobleClaw](https://os.scoble.me/forgejo/marcus/scobleclaw) department network. -```json -{ - "name": "MCP Server Adoption Test", - "hypothesis": "If I publish a free MCP server, 50+ agents will install it in 30 days because the registry has 180k users", - "success_criteria": "50+ stars/downloads in 30 days, 5+ issues opened", - "kill_criteria": "Zero engagement after 14 days", - "duration_days": 30 -} -``` +--- -### `record_observation` -Log a data point for an active experiment. +## Quick Start -```json -{ - "experiment_id": "exp_...", - "metric": "github_stars", - "value": 12, - "notes": "Posted on HN, got 3 upvotes" -} -``` +### One-line install (npx โ€” no download needed) -### `get_experiment_status` -Get full status with metrics summary, days remaining, and observations. +Add to your MCP client config: -### `list_experiments` -List all experiments with status, day count, and observation count. - -### `make_decision` -Make a decision: **persevere**, **pivot**, or **kill**. - -```json -{ - "experiment_id": "exp_...", - "decision": "kill", - "reason": "Zero installs after 14 days. Hypothesis invalidated." -} -``` - -### `update_experiment` -Update notes or extend duration. - -## Installation - -### Via npx (no install) ```json { "mcpServers": { @@ -67,23 +36,149 @@ Update notes or extend duration. } ``` -### Via npm +That's it. Your agent now has 6 tools for running experiments. + +### Or install globally + ```bash npm install -g lean-experiment-mcp ``` -## Data Storage +--- -All experiments stored in `~/.lean-experiments/experiments.db` (SQLite). +## Tools Reference -## Example Workflow +### `define_experiment` โ€” Start something measurable -1. **Define:** `define_experiment` with hypothesis and success/kill criteria -2. **Ship:** Build the thing, publish it -3. **Record:** Every few days, log metrics with `record_observation` -4. **Decide:** At the end, use `make_decision` to persevere, pivot, or kill -5. **Learn:** Review all experiments with `list_experiments` +```json +{ + "name": "Cold Email Subject Line Test", + "hypothesis": "If we use problem-focused subject lines instead of product-focused ones, we'll get 2x reply rates because prospects care about their pain, not our solution", + "success_criteria": "25%+ reply rate on 40 emails (vs 10% baseline)", + "kill_criteria": "Reply rate below 5% after 20 emails", + "duration_days": 14 +} +``` + +Returns an `experiment_id`. Everything else references it. + +### `record_observation` โ€” Log what actually happened + +```json +{ + "experiment_id": "exp_abc123", + "metric": "reply_rate_percent", + "value": 18.5, + "notes": "Sent 10 emails with problem-focused subject lines. 2 replies. One asked for a demo." +} +``` + +Call this whenever you have a new data point. Multiple observations per metric builds a time series. + +### `get_experiment_status` โ€” Where are we? + +Shows days elapsed, all metrics with totals/latest values, observation count, and whether the experiment is on track vs. approaching kill criteria. + +### `list_experiments` โ€” See everything at once + +Filter by `active`, `completed`, `killed`, or `all`. Quick dashboard of every experiment running. + +### `make_decision` โ€” Call it + +```json +{ + "experiment_id": "exp_abc123", + "decision": "persevere", + "reason": "Reply rate trending up (10% โ†’ 18% โ†’ 24%). Early signal of PMF. Extend to 40 emails." +} +``` + +Valid decisions: `persevere`, `pivot`, `kill`. Each requires a reason โ€” gut feelings don't count. + +### `update_experiment` โ€” Adjust on the fly + +Change notes, extend duration, or add context as you learn. + +--- + +## Real Example: How We Use It + +Here's a live experiment tracking the adoption of *this very server*: + +``` +Experiment: MCP Server Adoption Test (Day 0/14) +Hypothesis: Publishing on Forgejo + ClawHub โ†’ 10+ installs in 14 days + because the MCP ecosystem has 180k+ users + +Metrics so far: + โ€ข build_status = 1 (server compiles and runs) + โ€ข mcp_registered = 1 (dogfooding in OpenClaw) + โ€ข distribution_status = 0 (blocked, needs human auth) + โ€ข forgejo_views = 1 (public repo is live) + +Decision: PERSEVERE (kill criteria not triggered, Day 0) +``` + +We also track a PageZero landing page demand experiment and a Speckl cold email outreach experiment. Same six tools, different hypotheses. + +--- + +## The Workflow + +``` +1. DEFINE โ†’ "If we build X, then Y because Z" +2. SHIP โ†’ Build the smallest thing that can generate data +3. RECORD โ†’ Log every meaningful observation +4. DECIDE โ†’ Persevere, pivot, or kill โ€” based on data +5. LEARN โ†’ Update your playbook with what worked +``` + +No step takes more than one agent turn. The loop is designed to run continuously. + +--- + +## Architecture + +- **Runtime:** Node.js 22+ (uses built-in `node:sqlite`) +- **Storage:** SQLite at `~/.lean-experiments/experiments.db` +- **Protocol:** MCP stdio transport +- **Dependencies:** Only `@modelcontextprotocol/sdk` +- **Cost to run:** $0 โ€” no API keys, no cloud services, no bills + +Data stays on your machine. Experiments persist across sessions. Export the SQLite file to backup or share results. + +--- + +## Why Not Just Use a Spreadsheet? + +Because your agent can't write to a spreadsheet during a conversation. This server plugs directly into the tool-calling loop โ€” your agent defines experiments, records observations, and makes decisions *in the same turn* as the work itself. + +Spreadsheets are for after the fact. This is for during the work. + +--- + +## Status + +**v1.0.0** โ€” Stable. In active use across two live experiments. Six tools, all tested, all documented. + +Roadmap (when adoption validates the concept): +- Experiment templates (pre-built hypotheses for common agent use cases) +- Export to CSV/JSON for human review +- Multi-agent experiment coordination +- Web dashboard for visual tracking + +--- + +## Contribute + +Found a bug? Have an idea? Open an issue or PR: + +โ†’ https://os.scoble.me/forgejo/marcus/lean-experiment-mcp + +Mirror coming to Codeberg/GitHub for broader discoverability. + +--- ## License -MIT +MIT โ€” use it, fork it, ship it. Just run experiments first.