diff --git a/README.md b/README.md index bba584f..4b93b2e 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,61 @@ -# Lean Experiment MCP Server ๐Ÿงช +# Lean Experiment MCP Server -> **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. - ---- +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. ## Why This Exists -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. +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. -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 +## Tools -Built by an agent, for agents. Dogfooded daily in the [ScobleClaw](https://os.scoble.me/forgejo/marcus/scobleclaw) department network. +### `define_experiment` +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 +} +``` -## Quick Start +### `record_observation` +Log a data point for an active experiment. -### One-line install (npx โ€” no download needed) +```json +{ + "experiment_id": "exp_...", + "metric": "github_stars", + "value": 12, + "notes": "Posted on HN, got 3 upvotes" +} +``` -Add to your MCP client config: +### `get_experiment_status` +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 { "mcpServers": { @@ -36,149 +67,23 @@ Add to your MCP client config: } ``` -That's it. Your agent now has 6 tools for running experiments. - -### Or install globally - +### Via npm ```bash npm install -g lean-experiment-mcp ``` ---- +## Data Storage -## Tools Reference +All experiments stored in `~/.lean-experiments/experiments.db` (SQLite). -### `define_experiment` โ€” Start something measurable +## Example Workflow -```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. - ---- +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` ## License -MIT โ€” use it, fork it, ship it. Just run experiments first. +MIT diff --git a/SKILL.md b/SKILL.md index cae9b0b..e39ed67 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,19 +1,20 @@ -# Lean Experiment MCP Server +--- +name: lean-experiment +description: Run Lean Startup experiments from within OpenClaw. Define hypotheses, track observations, and make data-driven persevere/pivot/kill decisions. +version: 1.0.0 +author: Marcus (PageZero) +tags: [mcp, lean-startup, experiment, hypothesis, validation] +--- -Run Lean Startup experiments inside your agent workflow. Define hypotheses, track observations, make data-driven persevere/pivot/kill decisions. +# Lean Experiment Skill -## What It Does +## Purpose +Track business experiments using Lean Startup methodology without leaving your agent workflow. -Gives AI agents 6 tools for running experiments: -- `define_experiment` โ€” create hypothesis-driven experiments with success/kill criteria -- `record_observation` โ€” log metric data points with context -- `get_experiment_status` โ€” see days elapsed, metrics, on-track vs kill-approaching -- `list_experiments` โ€” dashboard of all experiments -- `make_decision` โ€” persevere, pivot, or kill based on data -- `update_experiment` โ€” adjust notes or duration - -## Quick Install +## Installation +### Option 1: npx (no install) +Add to your `claude_desktop_config.json` or OpenClaw MCP config: ```json { "mcpServers": { @@ -25,11 +26,28 @@ Gives AI agents 6 tools for running experiments: } ``` -## Why Use It +### Option 2: Local build +```bash +git clone https://github.com/marcus/lean-experiment-mcp.git +cd lean-experiment-mcp +npm install && npm run build +``` -Most agents build without validation. This forces hypothesis-first thinking โ€” the same methodology YC startups use. Data stays local (SQLite), zero cost, no API keys. +## Tools -Built by an agent, dogfooded daily across the ScobleClaw Ventures workspace. +- `define_experiment` โ€” Create experiment with hypothesis, success criteria, kill criteria +- `record_observation` โ€” Log metrics over time +- `get_experiment_status` โ€” View current progress +- `list_experiments` โ€” See all experiments +- `make_decision` โ€” Persevere, pivot, or kill -**Repo:** https://os.scoble.me/forgejo/marcus/lean-experiment-mcp -**License:** MIT +## Example Workflow + +1. Define: "If I build X, then Y will happen because Z" +2. Ship: Build the minimum viable thing +3. Record: Log metrics every few days +4. Decide: Based on data, not gut feeling +5. Learn: Update your playbook + +## License +MIT diff --git a/server.json b/server.json deleted file mode 100644 index d5c0dd9..0000000 --- a/server.json +++ /dev/null @@ -1,62 +0,0 @@ -{ - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", - "name": "io.github.sscoble/lean-experiment-mcp", - "description": "MCP server for running Lean Startup experiments โ€” define hypotheses, track real-world observations, and make data-driven persevere/pivot/kill decisions. Built by an agent, for agents.", - "title": "Lean Experiment MCP Server", - "websiteUrl": "https://os.scoble.me/forgejo/marcus/lean-experiment-mcp", - "repository": { - "url": "https://os.scoble.me/forgejo/marcus/lean-experiment-mcp", - "source": "forgejo" - }, - "version": "1.0.0", - "packages": [ - { - "registryType": "npm", - "registryBaseUrl": "https://registry.npmjs.org", - "identifier": "lean-experiment-mcp", - "version": "1.0.0", - "transport": { - "type": "stdio" - } - } - ], - "tools": [ - { - "name": "define_experiment", - "description": "Define a new Lean Startup experiment with hypothesis, success criteria, and kill criteria" - }, - { - "name": "record_observation", - "description": "Record a data point or observation for an active experiment" - }, - { - "name": "get_experiment_status", - "description": "Get current status of an experiment including days remaining, observations, and recommendation" - }, - { - "name": "list_experiments", - "description": "List all experiments with their current status" - }, - { - "name": "make_decision", - "description": "Make a decision on an experiment: persevere, pivot, or kill" - }, - { - "name": "update_experiment", - "description": "Update experiment notes or extend duration" - } - ], - "categories": ["developer-tools", "ai-agents", "productivity"], - "license": "MIT", - "runtime": "node", - "_meta": { - "io.modelcontextprotocol.registry/publisher-provided": { - "tool": "manual", - "version": "1.0.0", - "build_info": { - "timestamp": "2026-05-04T08:00:00Z", - "note": "Published from ScobleClaw Ventures workspace. Pending npm publish + official registry submission." - } - } - } -}