Milestone

io.github.LAHutchins91v1.0.1Updated Oct 5, 2026

Approved freelance milestone definitions and what done means, shared with AI assistants over MCP.

VerifiedStreamable HTTPWeb executableBusiness & CommerceProductivity & Workflow

Overview

AI-generated overview

Milestone stores a freelancer's approved milestone definitions and acceptance criteria so an assistant can read them before answering.

What it does
Milestone keeps a record of approved freelance milestones, the acceptance criteria that define what done means, saved deliverables and work items, and the wording an assistant may use with a client. Tools include list_milestone_sets, open_milestone_set, read_milestone_set, define_milestone, save_acceptance_criterion, save_deliverable, save_work_item, record_criterion_met, declare_milestone_complete, declare_next_payment_released, mark_work_done, write_client_wording, approve_milestones, suggest_milestone_change and accept_milestone_change. The server refuses to declare a milestone complete or a next payment released unless every saved acceptance criterion was met, and refuses extra…
When to use it
Use it when a freelancer wants an assistant to answer client questions about milestone status, deliverables and payment release from a saved, approved record rather than inventing progress. It suits workflows where completion claims must be tied to stored acceptance criteria.
Requirements
A remote Streamable HTTP endpoint with OAuth sign-in to a Milestone account; dynamic client registration means client id and secret stay empty. Tools need a Pro subscription or active trial. Self-hosting requires Node.js, npm install/test/typecheck/build/start, and server-side variables APP_BASE_URL, SUPABASE_URL, SUPABASE_ANON_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_MONTHLY and STRIPE_PRICE_YEARLY. Records are stored in a JSON file, default ~/.milestone/milestone.json…
Before you install
The server process needs secrets including SUPABASE_ANON_KEY, STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET, set on the server rather than in an MCP header; the README says not to paste an API key or password into a header. Tools write and change milestone records, including approve_milestones, declare_milestone_complete, declare_next_payment_released and accept_milestone_change, and payment release wording is tied to a Stripe subscription. One process owns the data file, and the README warns…

Installation

In SourceWeft

  1. Open Milestone in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "milestone": {
      "type": "http",
      "url": "https://milestone-continuity2.vercel.app/mcp"
    }
  }
}

README

Milestone

Milestone keeps a freelancer's approved milestone definitions and what done means, then lets an assistant read that record before it answers. An assistant cannot say a milestone is complete, or that the next payment is released, unless the saved acceptance criteria were met. It cannot invent an extra deliverable or mark work done that was not saved.

It works with ChatGPT, Claude, Gemini, Grok, and Cursor, plus any other MCP client that can do Streamable HTTP and OAuth. It is not a ChatGPT-only plugin.

Sign in with your Milestone account when the assistant opens OAuth. Do not paste an API key or password into a header. Milestone supports dynamic client registration: leave the client id and secret empty. The protected-resource metadata at /.well-known/oauth-protected-resource/mcp points clients at the OAuth issuer, which registers them.

Milestone tools need Pro or an active trial. A new subscription includes a 14-day trial. This page does not list a price. Checkout shows the billing interval and payment terms.

There is no hosted production domain in this repository. Run the server yourself and use the base URL you configure. The default MCP address is http://127.0.0.1:3000/mcp.

What the assistant can do

After you approve the connection, the server exposes these tools:

  • list_milestone_sets
  • open_milestone_set
  • read_milestone_set
  • define_milestone
  • save_acceptance_criterion
  • save_deliverable
  • save_work_item
  • record_criterion_met
  • declare_milestone_complete
  • declare_next_payment_released
  • mark_work_done
  • write_client_wording
  • approve_milestones
  • suggest_milestone_change
  • accept_milestone_change

read_milestone_set is the read the assistant should do before it answers. It includes the milestone definitions, the acceptance criteria that say what done means, the saved deliverables and work, and what the assistant may tell the client. Draft definitions are not an approved commitment. A suggested milestone change does not change the record. After the milestones are approved, declare_milestone_complete refuses to call a milestone complete and declare_next_payment_released refuses to say the next payment is released unless every saved acceptance criterion on that milestone was met. save_deliverable refuses an extra deliverable, and mark_work_done refuses work that was not saved. Those additions go through suggest_milestone_change and then accept_milestone_change, and only when you explicitly approve that change.

The assistant only calls these tools when you and the host allow it.

Connect

Cursor, in ~/.cursor/mcp.json or a project .cursor/mcp.json:

json
{  "mcpServers": {    "milestone": {      "url": "http://127.0.0.1:3000/mcp"    }  }}

Do not add a headers block. Cursor registers a client and opens sign-in.

Claude Code:

bash
claude mcp add --transport http milestone http://127.0.0.1:3000/mcp

Do not pass an Authorization header. Other clients use the same address, choose OAuth, and leave client id and secret empty. Steps for ChatGPT, Claude, Gemini, Grok, and Cursor are on the connect page at /connect.

Registry metadata for this server is in server.json (io.github.LAHutchins91/milestone). The public remote MCP URL there is https://milestone-continuity2.vercel.app/mcp.

Run

bash
npm installnpm testnpm run typechecknpm run buildnpm start

When stdin is a terminal, Milestone serves Streamable HTTP on port 3000. When stdin is not a terminal, it speaks MCP over stdio and still opens the HTTP port. Logs during stdio mode go to stderr so they do not mix with the protocol.

Records are stored durably in a JSON file. The default path is ~/.milestone/milestone.json. Set MILESTONE_DATA_PATH to move it. One server process owns that file. Do not point it at another product's data file.

OAuth uses the same idea as a Supabase authorization server with dynamic client registration. Set these on the server process, not in an MCP header:

  • APP_BASE_URL (default http://localhost:3000)
  • SUPABASE_URL
  • SUPABASE_ANON_KEY
  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET
  • STRIPE_PRICE_MONTHLY and STRIPE_PRICE_YEARLY (Stripe catalog ids, not a product price)

Tool calls other than discovery require a signed-in account whose subscription status is active or trialing.

Source: README.md at commit 4c52f75

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v1.0.1LatestOct 5, 2026