@stellar-agent-services/dev-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stellar Agent Services contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @stellar-agent-services/dev-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server for coding agents that build on [Provider Standard v1](../../docs/provider-standard.md): a provider,
+a gateway config, a native implementation or a paying client. It answers from this repository's documents and runs
+the verifier's unpaid checks.
+
+**It holds no key and never pays.** It is not the payment client's MCP server, which would let an agent hire
+providers. That one is planned in [packages/payment-client](../payment-client/README.md).
+
+| Tool | What it does |
+| --- | --- |
+| `list_docs` | The documentation index, [llms.txt](../../llms.txt) |
+| `read_doc` | One document from that index, by repository path (`AGENTS.md`, `docs/provider-standard.md`) or llms.txt URL. Nothing outside the index can be read. |
+| `search_docs` | Lines of the indexed documents that contain every term of a query, as `path:line` |
+| `get_spec_rule` | A rule of the standard by id (`J13`, `[M5]`), with its section |
+| `validate_manifest` | Check C1 on a manifest document before it is served: JSON Schema [M9], the rules it can't express, service schemas, SHOULD rules. Same code as the verifier. |
+| `check_provider` | `verifier check` on a running provider: C1, C2, C3, C6 and an unpaid C7 burst. C4 and C5 need a payer, so they are skipped. |
+
+## Use
+
+```bash
+# Claude Code
+claude mcp add stellar-agent-services -- npx -y @stellar-agent-services/dev-mcp
+```
+
+Any other MCP client takes the same command as a stdio server:
+
+```json
+{
+  "mcpServers": {
+    "stellar-agent-services": { "command": "npx", "args": ["-y", "@stellar-agent-services/dev-mcp"] }
+  }
+}
+```
+
+Installed from npm, it reads the documents packed with it in `repository/`, from the same commit as its code. Run from
+a clone instead (`node packages/dev-mcp/dist/index.js`, after `npm install && npm run build`), it reads the clone's
+documents, so `git pull && npm run build` updates it.
+
+As a library, `createServer(options)` returns the `McpServer`. `options.verify` passes options to
+`verifyProvider()`, such as an offline provider's `fetch` in tests. It never takes a payer.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `src/server.ts` | `createServer()`: the tools |
+| `src/docs.ts` | The llms.txt index, document reads and search, spec rule parsing |
+| `src/index.ts` | The stdio entry point |
+| `scripts/pack-docs.mjs` | Before npm packs the package: copies llms.txt and every document it links to into `repository/` |
+| `test/server.test.ts` | Every tool through a real MCP client; `check_provider` against the verifier's offline provider |

package/dist/docs.d.ts

@@ -0,0 +1,35 @@
+export interface DocEntry {
+    /** Repository path, such as docs/provider-standard.md. */
+    path: string;
+    title: string;
+    summary: string;
+    /** The llms.txt section, such as "Build a provider". */
+    section: string;
+}
+export interface SpecRule {
+    id: string;
+    /** The heading the rule is under, such as "5.4 Processing order". */
+    section: string;
+    text: string;
+}
+export interface SearchHit {
+    path: string;
+    line: number;
+    text: string;
+}
+export declare class Docs {
+    private readonly root;
+    readonly index: string;
+    readonly entries: DocEntry[];
+    private rules;
+    constructor(root: URL);
+    /** The entry for a repository path or its raw GitHub URL, when llms.txt lists it. */
+    entry(pathOrUrl: string): DocEntry | undefined;
+    read(entry: DocEntry): string;
+    /** Lines containing every term of the query, case-insensitive, in llms.txt order. */
+    search(query: string, limit: number): SearchHit[];
+    /** A spec rule by id: "J13", "[J13]" or "j13". */
+    rule(id: string): SpecRule | undefined;
+    ruleIds(): string[];
+}
+//# sourceMappingURL=docs.d.ts.map

package/dist/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,IAAI;IAKH,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC7B,OAAO,CAAC,KAAK,CAAoC;gBAEpB,IAAI,EAAE,GAAG;IAKtC,qFAAqF;IACrF,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAK9C,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IAI7B,qFAAqF;IACrF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE;IAgBjD,kDAAkD;IAClD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAKtC,OAAO,IAAI,MAAM,EAAE;CAIpB"}

package/dist/docs.js

@@ -0,0 +1,92 @@
+// The documents the server reads, and the spec's rules.
+//
+// llms.txt at the repository root is the index: only the files it links to can be read or searched, so a
+// tool call can't reach anything else on disk. Rules are the `- **[ID]**` bullets of
+// docs/provider-standard.md, each with the section it belongs to.
+import { readFileSync } from "node:fs";
+const RAW = "https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/";
+const SPEC = "docs/provider-standard.md";
+const RULE = /^- \*\*\[([A-Z]\d+)\]\*\*\s*(.*)$/;
+export class Docs {
+    root;
+    index;
+    entries;
+    rules;
+    constructor(root) {
+        this.root = root;
+        this.index = readFileSync(new URL("llms.txt", root), "utf8");
+        this.entries = parseIndex(this.index);
+    }
+    /** The entry for a repository path or its raw GitHub URL, when llms.txt lists it. */
+    entry(pathOrUrl) {
+        const path = (pathOrUrl.startsWith(RAW) ? pathOrUrl.slice(RAW.length) : pathOrUrl).replace(/^\.?\//, "");
+        return this.entries.find((entry) => entry.path === path);
+    }
+    read(entry) {
+        return readFileSync(new URL(entry.path, this.root), "utf8");
+    }
+    /** Lines containing every term of the query, case-insensitive, in llms.txt order. */
+    search(query, limit) {
+        const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const hits = [];
+        if (terms.length === 0)
+            return hits;
+        for (const entry of this.entries) {
+            const lines = this.read(entry).split("\n");
+            for (const [index, text] of lines.entries()) {
+                const lower = text.toLowerCase();
+                if (!terms.every((term) => lower.includes(term)))
+                    continue;
+                hits.push({ path: entry.path, line: index + 1, text: text.trim() });
+                if (hits.length >= limit)
+                    return hits;
+            }
+        }
+        return hits;
+    }
+    /** A spec rule by id: "J13", "[J13]" or "j13". */
+    rule(id) {
+        this.rules ??= parseRules(readFileSync(new URL(SPEC, this.root), "utf8"));
+        return this.rules.get(id.replace(/[[\]\s]/g, "").toUpperCase());
+    }
+    ruleIds() {
+        this.rules ??= parseRules(readFileSync(new URL(SPEC, this.root), "utf8"));
+        return [...this.rules.keys()];
+    }
+}
+function parseIndex(index) {
+    const entries = [];
+    let section = "";
+    for (const line of index.split("\n")) {
+        if (line.startsWith("## "))
+            section = line.slice(3).trim();
+        const link = /^- \[([^\]]+)\]\(([^)]+)\)(?::\s*(.*))?$/.exec(line);
+        if (link === null || !link[2].startsWith(RAW))
+            continue;
+        entries.push({ path: link[2].slice(RAW.length), title: link[1], summary: link[3] ?? "", section });
+    }
+    return entries;
+}
+function parseRules(spec) {
+    const rules = new Map();
+    let section = "";
+    let current;
+    for (const line of spec.split("\n")) {
+        const heading = /^#{2,4} (.*)$/.exec(line);
+        if (heading !== null)
+            section = heading[1].trim();
+        const rule = RULE.exec(line);
+        if (rule !== null) {
+            current = { id: rule[1], section, text: rule[2] };
+            rules.set(current.id, current);
+        }
+        else if (current !== undefined && line.startsWith("  ") && line.trim() !== "") {
+            current.text += ` ${line.trim()}`;
+        }
+        else {
+            current = undefined;
+        }
+    }
+    return rules;
+}
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The MCP server over stdio. Everything is in server.ts; this only connects it to the process.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+await createServer().connect(new StdioServerTransport());
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,+FAA+F;AAE/F,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type VerifyOptions } from "@stellar-agent-services/verifier";
+export declare const SERVER: {
+    readonly name: "stellar-agent-services";
+    readonly version: string;
+};
+export interface ServerOptions {
+    /** The repository the documents are read from. Default: the clone this server is built in. */
+    root?: URL;
+    /** Passed to verifyProvider() by check_provider, such as an offline provider's fetch in tests. Never a payer. */
+    verify?: Omit<Partial<VerifyOptions>, "payer">;
+}
+export declare function createServer(options?: ServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAA8D,KAAK,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAOlI,eAAO,MAAM,MAAM;;;CAAuD,CAAC;AAO3E,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,iHAAiH;IACjH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,CAAC;CAChD;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,SAAS,CAmHnE"}

package/dist/server.js

@@ -0,0 +1,125 @@
+// The MCP server for coding agents that build on Provider Standard v1.
+//
+// Tools:
+//   list_docs          the documentation index (llms.txt)
+//   read_doc           one document from that index
+//   search_docs        lines of the indexed documents that contain every term of a query
+//   get_spec_rule      a rule of the standard by id, such as J13
+//   validate_manifest  check C1 on a manifest document that is not served yet
+//   check_provider     `verifier check` on a running provider: C1, C2, C3, C6 and C7's unpaid burst
+//
+// It holds no key and never pays: check_provider runs without a test payer, so the paid checks (C4, C5)
+// are always skipped. The documents are read from the clone the server is built in, or, installed from npm, from the
+// copy of them packed with it (scripts/pack-docs.mjs).
+import { existsSync, readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PROVIDER_STANDARD } from "@stellar-agent-services/protocol";
+import { checkManifestDocument, InvalidOptionsError, verifyProvider } from "@stellar-agent-services/verifier";
+import { z } from "zod/v4";
+import { Docs } from "./docs.js";
+const PACKAGE = new URL("../", import.meta.url);
+const { version } = JSON.parse(readFileSync(new URL("package.json", PACKAGE), "utf8"));
+export const SERVER = { name: "stellar-agent-services", version };
+/** The clone this file is built in (dist/ is two levels below it), or else the documents packed in repository/. */
+const CLONE = new URL("../../../", import.meta.url);
+const REPOSITORY = existsSync(new URL("packages/dev-mcp/package.json", CLONE)) ? CLONE : new URL("repository/", PACKAGE);
+const MAX_SEARCH_HITS = 50;
+export function createServer(options = {}) {
+    const docs = new Docs(options.root ?? REPOSITORY);
+    const server = new McpServer(SERVER, {
+        instructions: `Tools for building on ${PROVIDER_STANDARD}, the standard for paid AI services on Stellar. ` +
+            "Start with read_doc on AGENTS.md to pick a path. Cite spec rules by id and look them up with get_spec_rule. " +
+            "Check a manifest with validate_manifest while writing it, and a running provider with check_provider. Nothing here pays.",
+    });
+    server.registerTool("list_docs", {
+        title: "List documents",
+        description: "The documentation index (llms.txt): every guide, reference and schema, with a one-line summary. read_doc takes any path it lists.",
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => text(docs.index));
+    server.registerTool("read_doc", {
+        title: "Read a document",
+        description: "Reads one document listed by list_docs, by repository path (such as docs/provider-standard.md or AGENTS.md) or by its llms.txt URL.",
+        inputSchema: { path: z.string().describe("Repository path or llms.txt URL") },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ path }) => {
+        const entry = docs.entry(path);
+        if (entry === undefined)
+            return error(`${path} is not in the index. Paths you can read:\n${docs.entries.map((known) => known.path).join("\n")}`);
+        return text(docs.read(entry));
+    });
+    server.registerTool("search_docs", {
+        title: "Search the documents",
+        description: "Finds lines that contain every term of the query, case-insensitive, across the indexed documents. Returns path:line and the line.",
+        inputSchema: {
+            query: z.string().min(1).describe("Terms, such as \"payment_uncertain reconcile\""),
+            limit: z.number().int().min(1).max(MAX_SEARCH_HITS).optional().describe(`Most hits to return (default 20, at most ${MAX_SEARCH_HITS})`),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ query, limit }) => {
+        const hits = docs.search(query, limit ?? 20);
+        if (hits.length === 0)
+            return text(`No line contains every term of "${query}".`);
+        return text(hits.map((hit) => `${hit.path}:${hit.line}: ${hit.text}`).join("\n"));
+    });
+    server.registerTool("get_spec_rule", {
+        title: "Get a spec rule",
+        description: "The full text of a Provider Standard v1 rule by id, such as M5, P7, J13 or Q1, with its section. Prefixes: M manifest, S services, P payment, J jobs, Q capacity, E errors, I identity, X extensions.",
+        inputSchema: { id: z.string().describe("Rule id, such as J13 or [J13]") },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ id }) => {
+        const rule = docs.rule(id);
+        if (rule === undefined)
+            return error(`No rule ${id}. Rules: ${docs.ruleIds().join(", ")}`);
+        return text(`[${rule.id}] (docs/provider-standard.md, ${rule.section})\n${rule.text}`);
+    });
+    server.registerTool("validate_manifest", {
+        title: "Validate a manifest",
+        description: "Runs check C1 on a manifest document before it is served: the JSON Schema [M9], the rules JSON Schema can't express (M3, M5, M7, S6, S9, P11), the service schemas, and SHOULD rules. Serving rules (status, Content-Type, redirects, Cache-Control) need check_provider on the running provider.",
+        inputSchema: {
+            manifest: z.string().describe("The manifest's JSON text"),
+            manifestUrl: z.string().optional().describe("Where it will be served. Default: /.well-known/stellar-agent-services.json on the origin of its baseUrl"),
+            dev: z.boolean().optional().describe("Accept a loopback http:// provider [M6]"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ manifest, manifestUrl, dev }) => {
+        const result = await checkManifestDocument(manifest, { ...(manifestUrl === undefined ? {} : { manifestUrl }), dev: dev ?? false });
+        return text(`${describe(result)}\n\n${JSON.stringify(result, null, 2)}`);
+    });
+    server.registerTool("check_provider", {
+        title: "Check a running provider",
+        description: "Runs `verifier check` on a provider's manifest URL: C1 manifest, C2 identity, C3 challenge, C6 hygiene and an unpaid load burst (C7, 20 requests). It never pays, so C4 and C5 are skipped. Sends requests to the provider.",
+        inputSchema: {
+            manifestUrl: z.string().describe("Such as https://api.example.com/.well-known/stellar-agent-services.json"),
+            dev: z.boolean().optional().describe("Accept a provider on http://localhost [M6]"),
+            service: z.string().optional().describe("The service to probe and load. Default: the cheapest one with an example"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ manifestUrl, dev, service }) => {
+        const { payer: _never, ...overrides } = (options.verify ?? {});
+        try {
+            const report = await verifyProvider({ ...overrides, manifestUrl, dev: dev ?? false, ...(service === undefined ? {} : { service }) });
+            const lines = report.results.map(describe);
+            lines.push("", `Level ${report.level}, score ${report.score} of 100. Paid checks (C4, C5) need \`verifier verify --pay\` with a funded testnet payer.`);
+            return text(`${lines.join("\n")}\n\n${JSON.stringify(report, null, 2)}`);
+        }
+        catch (caught) {
+            if (caught instanceof InvalidOptionsError)
+                return error(caught.message);
+            throw caught;
+        }
+    });
+    return server;
+}
+/** One line for a check, then its findings. */
+function describe(result) {
+    const head = `${result.status === "passed" ? "✓" : result.status === "failed" ? "✗" : "-"} ${result.check} ${result.status}${result.reason === undefined ? "" : `: ${result.reason}`}`;
+    const findings = (result.findings ?? []).map((finding) => `    ${finding.severity} [${finding.rule}] ${finding.message}`);
+    return [head, ...findings].join("\n");
+}
+function text(value) {
+    return { content: [{ type: "text", text: value }] };
+}
+function error(value) {
+    return { content: [{ type: "text", text: value }], isError: true };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@stellar-agent-services/dev-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server for coding agents building on Provider Standard v1: spec rules, docs, manifest validation and unpaid provider checks. It never pays.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlgoriaLabs/stellar-agent-services.git",
+    "directory": "packages/dev-mcp"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "repository",
+    "!dist/.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "node scripts/pack-docs.mjs"
+  },
+  "bin": {
+    "stellar-agent-services-mcp": "./dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@stellar-agent-services/protocol": "0.1.1",
+    "@stellar-agent-services/verifier": "0.1.1",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@stellar-agent-services/provider-kit": "0.1.1"
+  }
+}

package/repository/AGENTS.md

@@ -0,0 +1,162 @@
+# AGENTS.md
+
+Instructions for AI coding agents. Read this first, pick one path in §2, then follow the reference it names.
+People should start with [README.md](README.md).
+
+## 1. What this is
+
+**Provider Standard v1** (`stellar-agent-services/provider@1`) is an open standard for paid AI services on
+Stellar. A provider publishes a manifest at `/.well-known/stellar-agent-services.json` that describes its services,
+prices and schemas. A client pays per job in USDC through x402 v2 (`exact` scheme). If the client loses the
+response, it collects the result again without paying twice.
+
+This repository holds the standard and everything needed to use it:
+
+| Piece | Path | What it is |
+| --- | --- | --- |
+| The standard | [docs/provider-standard.md](docs/provider-standard.md) | Normative. Rules have ids such as `[M5]` and `[J13]`. |
+| Protocol | [packages/protocol](packages/protocol) | The standard as TypeScript with no runtime dependencies, plus JSON Schemas and test vectors |
+| Provider Kit | [packages/provider-kit](packages/provider-kit) | Library (`defineService`, `createProvider`), gateway for an existing API, `provider-kit` CLI |
+| Payment client | [packages/payment-client](packages/payment-client) | Buyer side: approval, spending policy, journal, payment, recovery. `stellar-pay` CLI. |
+| Verifier | [packages/verifier](packages/verifier) | Checks a provider against the standard (C1–C7), issues receipts and badges. `verifier watch` answers validation requests by itself. |
+| MCP server | [packages/dev-mcp](packages/dev-mcp) | Spec rules, docs, manifest validation and provider checks as MCP tools. It never pays. |
+| Scaffolder | [packages/create-stellar-service](packages/create-stellar-service) | `npm create stellar-service`: a new project around an existing API, a TypeScript service or a Python service, ready to run, try and deploy |
+| Agent Wallet | [apps/wallet](apps/wallet) | Web page where a person approves and pays |
+| Examples | [examples/paid-service](examples/paid-service), [examples/python-upstream](examples/python-upstream) | A TypeScript provider, and a Python API behind the gateway |
+
+Facts to get right:
+
+- **Networks:** `stellar:testnet` and `stellar:pubnet`. Everything here is developed and tested on testnet.
+- **Asset:** USDC only. Take its contract address from `USDC_ASSET[network]` in `@stellar-agent-services/protocol`
+  instead of retyping it.
+- **Facilitator:** `https://x402.org/facilitator` on testnet. It verifies and settles payments with sponsored fees.
+  On mainnet, OpenZeppelin's `https://channels.openzeppelin.com/x402`, which wants an API key (`FACILITATOR_AUTH`).
+- **Identity:** a provider registers in the Stellar 8004 identity registry. Its `agentId` goes in the manifest, and
+  its registered wallet must equal `payTo` (`[I1]`–`[I3]`).
+- **Node.js 22.13 or later.** `.node-version` pins 24.
+
+## 2. Pick a path
+
+| You want to… | Path | Read | Done when |
+| --- | --- | --- | --- |
+| Build a **new paid service** in TypeScript (Node, Workers, Deno, Bun) | Kit library. `create-stellar-service --kind typescript` makes the project. | [docs/standard/README-AI.md §2](docs/standard/README-AI.md#2-kit-path-typescript), [provider-setup-guide.md §3b](docs/provider-setup-guide.md#3b-typescript-library-a-new-service), template [examples/paid-service](examples/paid-service) | `provider-kit check --manifest <url> --dev` and `verifier check <url> --dev` pass |
+| Make an **existing HTTP API** paid, in any language | Gateway: a JSON config, no code. `provider-kit init --openapi <url>` writes it from the API's OpenAPI document; `create-stellar-service --kind wrap` makes a whole project around it. | [provider-setup-guide.md §3a](docs/provider-setup-guide.md#3a-gateway-an-existing-api), [packages/provider-kit](packages/provider-kit#gateway-mode), [examples/python-upstream](examples/python-upstream) | `provider-kit check --config provider.config.json` passes and the gateway starts |
+| Implement the standard in **another language** | Native | [docs/standard/README-AI.md §3–§13](docs/standard/README-AI.md), the [spec](docs/provider-standard.md), the [test vectors](packages/protocol/test-vectors) | Every test vector passes, and `verifier check <url>` passes |
+| Build an **agent, wallet or app that pays** providers | Client: an adapter for `payment-client`, or your own client | [docs/client-integration/README-AI.md](docs/client-integration/README-AI.md), spec §14 rules in [docs/standard/README-AI.md](docs/standard/README-AI.md#14-client-rules-agents-wallets-apps) | The conformance checks in `@stellar-agent-services/payment-client/conformance` pass, or for a native client the client rules hold |
+| **Verify** a provider, or get one verified | Verifier | [docs/verification.md](docs/verification.md), [packages/verifier](packages/verifier), [provider-setup-guide.md §7–§9](docs/provider-setup-guide.md#7-go-live-provider-kit-launch) | `verifier check` passes; with a funded test payer, `verifier verify --pay` reaches the level you need |
+| **Change this repository** | Contributor | §6 below, [CONTRIBUTING.md](CONTRIBUTING.md), and for recovery code [docs/recovery/README-AI.md](docs/recovery/README-AI.md) | `npm run typecheck` and `npm test` pass |
+
+Follow one path. Don't mix the Kit with a hand-written job flow.
+
+## 3. Use the packages from another project
+
+The packages are on npm, all at one version:
+
+```bash
+npm create stellar-service my-service -- --kind wrap|typescript|python   # a new project, ready to run
+npm install @stellar-agent-services/provider-kit      # a provider in your own project
+npm install @stellar-agent-services/payment-client    # an agent or app that pays
+npx @stellar-agent-services/verifier check <url>      # also provider-kit, and stellar-pay (payment-client)
+```
+
+`npm create stellar-service` makes a project around the kit: it installs it and writes `.env`, a Dockerfile, `fly.toml`
+and npm scripts: `dev` (runs it, paid to a throwaway testnet account, so no wallet is needed), `try`, `check`,
+`status`, `launch` (goes live) and `deploy`. Pass every answer as a flag (`--openapi`, `--upstream`, `--description`,
+`--price`): without a terminal it asks nothing. `--network mainnet` makes a project that takes real USDC: use it only
+when the user asked for mainnet. Such a project has no `try`, since mainnet has no test money: build and try it on
+testnet first.
+
+Installing the kit into a project of your own, add the override `create-stellar-service` writes to its
+`package.json`, which keeps one copy of the Stellar SDK: `"overrides": { "@trionlabs/stellar8004": {
+"@stellar/stellar-sdk": "16.4.1" } }` ([provider-kit README](packages/provider-kit/README.md)).
+
+`npm run launch` (`provider-kit launch`) opens an approval page in the user's browser, where their wallet signs the
+trustline, the 8004 registration and a validation request in one go, and it may deploy to Fly.io. Ask the user
+first, run it with `--no-open`, and give them the link. `provider-kit status --json` tells you where a provider stands
+and the one command to run next.
+
+A native implementation needs no package: it needs the spec, `packages/protocol/schemas/manifest.schema.json` and
+the test vectors. Changes not released yet run from a clone (`npm install && npm run build`): there,
+`node packages/create-stellar-service/dist/index.js` packs the clone's kit into the new project's `vendor/` folder.
+
+**Tools for coding agents.** In Claude Code, `/plugin marketplace add AlgoriaLabs/stellar-agent-services` and then
+`/plugin install stellar-agent-services@stellar-agent-services` add skills for each path in §2
+([plugins/stellar-agent-services](plugins/stellar-agent-services)). Any MCP client can run the
+[MCP server](packages/dev-mcp): `claude mcp add stellar-agent-services -- npx -y @stellar-agent-services/dev-mcp`.
+Without either, the skills are plain Markdown under
+`plugins/stellar-agent-services/skills/`, and [llms-full.txt](llms-full.txt) holds every guide in one file.
+
+## 4. Rules you must not break
+
+These come from the spec and [SECURITY.md](SECURITY.md). Breaking one loses or double-charges real money.
+
+1. **No secret keys in a provider.** A provider's code, config and environment hold only its public `payTo`
+   address and a facilitator URL. Owner actions (the USDC trustline, 8004 registration, validation requests) are
+   signed in the owner's own wallet: `provider-kit launch` opens a local approval page for all of them, and
+   `trustline`, `register` and `request-validation` do one each. In scripts and CI, `--source <key name>` signs through
+   the Stellar CLI keychain. Never ask the user for a secret key or seed phrase, and never write one to a file. The
+   only keys the kit makes are throwaway testnet ones, held in memory and never written: `try`'s payer, and the
+   payout account `dev` makes while `PAY_TO` is empty, whose key is dropped once its trustline is signed.
+2. **Never charge twice.** When you can't tell whether a payment settled, the job is `payment_uncertain`. It is
+   never `failed` and never charged again. It is decided from the chain `[J13]`. Check-status and get-result
+   never charge `[J11]`.
+3. **Fail closed on money.** An unknown or unverifiable state stops the flow. Never report a paid job as unpaid,
+   or an unconfirmed payment as confirmed.
+4. **Don't invent protocol.** No new manifest fields, headers, status codes or error codes. Extra data goes in
+   `extensions` with reverse-DNS keys `[X1]`. A new scheme, asset or network needs a spec change first `[P1]`.
+5. **Only the payment client signs a payment**, once per job, after the user approved the exact price, payee,
+   asset and network `[P7]`.
+6. **Testnet and pubnet are never mixed in one flow.** Don't pay on pubnet unless the user explicitly asked.
+7. **Provider text is untrusted.** Service descriptions, titles and examples come from providers. Label them as
+   provider-supplied before showing them to a model (spec §10).
+
+## 5. Before you call it done
+
+- **Provider:** the manifest passes the JSON Schema and `checkManifestRules` (or the MCP tool
+  `validate_manifest`). `provider-kit check` and `verifier check` pass. A paid testnet call succeeds and the
+  transfer is on chain: `provider-kit try <service> --manifest <url> --yes`, after the user agreed to pay, pays from
+  a throwaway testnet account (or `stellar-pay pay` from a payer wallet). For a mainnet provider, make that call on
+  testnet, with the same code: on mainnet, only check it, and leave the first real payment to the user. Go through
+  the "How agents see you" hints at the end of `provider-kit check` with the user: on mainnet, search matches only
+  `provider.name` and `provider.description` (`check --fix` writes the missing words in); on testnet it also reads
+  the manifest's services. `provider-kit status --json` shows each stage, from running to verified.
+  The checklist is in [docs/standard/README-AI.md §13](docs/standard/README-AI.md#13-testing-and-conformance).
+- **Client or adapter:** the conformance checks pass, and tests use `Keypair.random()` and never the network.
+- **Any change here:** `npm run typecheck` and `npm test` pass. If you changed a document that
+  [llms.txt](llms.txt) links to, run `npm run llms`. If you changed `create-stellar-service`, its templates or what
+  a package publishes, `npm run scaffold:check` (for each kind and network you touched) and `npm run packages:check`
+  pass too.
+
+Cite spec rules by id in code comments, findings and error messages, as the existing code does.
+
+## 6. Working in this repository
+
+```bash
+npm install
+npm run typecheck     # tsc -b over every package
+npm test              # vitest, the whole workspace, offline
+npm run llms          # rebuild llms-full.txt after a doc change (CI checks it)
+
+npm run build && npm run packages:check   # what each npm package would publish
+npm run scaffold:check -- --kind typescript --network mainnet   # a new project: made, built, started, verified
+npm run packages:rehearse                 # publish to a throwaway local registry, then install and use the packages
+npm run live:check                        # read-only checks against the live networks: facilitators, RPC, registries
+```
+
+- **CI** runs all of these on every pull request except `live:check`, which runs daily
+  ([CONTRIBUTING.md](CONTRIBUTING.md#what-ci-checks)). The project checks and the rehearsal install from the npm
+  registry, and `live:check` reads the live networks. None of them signs or pays. A release is a version tag
+  ([CONTRIBUTING.md](CONTRIBUTING.md#releasing)).
+
+- **Order of change:** the spec is the product. A new behavior becomes a spec rule first
+  ([docs/provider-standard.md](docs/provider-standard.md)), then the Kit and the payment client, then a verifier
+  check that fails a provider breaking it. v1 is frozen and only gains optional fields and SHOULD rules.
+- **Tests never touch the network.** Providers in tests use `rpc: false` or a fake `ChainReader`. Payments are signed
+  offline (`@stellar-agent-services/provider-kit/testing`). Shared harnesses are in each package's `test/support/`.
+- **`packages/protocol` has no runtime dependencies** and never imports signing code. The read-only discovery
+  service depends on it.
+- **Style:** TypeScript strict, ES modules, `.js` import suffixes, exact dependency versions. Each file starts
+  with a comment that says what it does. Documents use short, plain sentences and wrap at about 115 characters.
+- **Layout:** `packages/<name>/src`, `packages/<name>/test`, one README per package with a file table. Find the file
+  map in each package README before you search.
+- Don't commit `.env` files, keys, journals or job databases (`.gitignore` covers them).