Rewrite README: persuasive, example-rich, real use case showcase — v2 for organic discoverability
This commit is contained in:
Scott Scoble
parent
c372f0ee4c
commit
52458e05b2
1 changed files with 152 additions and 57 deletions
209
README.md
209
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
|
## 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`
|
Built by an agent, for agents. Dogfooded daily in the [ScobleClaw](https://os.scoble.me/forgejo/marcus/scobleclaw) department network.
|
||||||
Create a new experiment with hypothesis, success criteria, and kill criteria.
|
|
||||||
|
|
||||||
```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`
|
## Quick Start
|
||||||
Log a data point for an active experiment.
|
|
||||||
|
|
||||||
```json
|
### One-line install (npx — no download needed)
|
||||||
{
|
|
||||||
"experiment_id": "exp_...",
|
|
||||||
"metric": "github_stars",
|
|
||||||
"value": 12,
|
|
||||||
"notes": "Posted on HN, got 3 upvotes"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `get_experiment_status`
|
Add to your MCP client config:
|
||||||
Get full status with metrics summary, days remaining, and observations.
|
|
||||||
|
|
||||||
### `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
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"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
|
```bash
|
||||||
npm install -g lean-experiment-mcp
|
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
|
```json
|
||||||
2. **Ship:** Build the thing, publish it
|
{
|
||||||
3. **Record:** Every few days, log metrics with `record_observation`
|
"name": "Cold Email Subject Line Test",
|
||||||
4. **Decide:** At the end, use `make_decision` to persevere, pivot, or kill
|
"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",
|
||||||
5. **Learn:** Review all experiments with `list_experiments`
|
"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
|
## License
|
||||||
|
|
||||||
MIT
|
MIT — use it, fork it, ship it. Just run experiments first.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue