Skip to content

Commit 0b8db0d

Browse files
brendanjryanbrendanjryan
authored
docs: improve agentic discovery score (#779)
1 parent 11c10b9 commit 0b8db0d

25 files changed

Lines changed: 476 additions & 12 deletions

‎public/.well-known/agent-skills/index.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"type": "skill-md",
77
"description": "TypeScript SDK for the Payment HTTP Authentication Scheme. Handles 402 Payment Required flows with Tempo, Stripe, and other payment methods. Use when integrating payments or mppx into a client or server application.",
88
"url": "/.well-known/agent-skills/mppx/SKILL.md",
9-
"digest": "sha256:9520d231fd7ae64ce54c8176e870a36d758c272748ceeadc7a3a8d23c2b8a5ce"
9+
"digest": "sha256:45039f241e97036627d9cf2b2864408fa6b6afb70faf7f0001ffc8eb5ceaece6"
1010
}
1111
]
1212
}

‎public/.well-known/agent-skills/mppx/SKILL.md‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,32 @@ description: TypeScript SDK for the Payment HTTP Authentication Scheme. Handles
77

88
TypeScript SDK for the "Payment" HTTP Authentication Scheme. Full 402 flow: challenge → credential → receipt.
99

10+
## What I can accomplish
11+
12+
- Add `402` payment handling to a client with `Fetch.polyfill` or `Fetch.from`.
13+
- Protect HTTP routes with server-side MPP Challenges and Receipt responses.
14+
- Accept one-time Tempo stablecoin payments with `tempo.charge`.
15+
- Accept metered Tempo stablecoin payments with `tempo.session`.
16+
- Accept one-time card payments with `stripe.charge`.
17+
- Verify Credentials directly for custom transports or background workflows.
18+
- Wrap MCP clients and servers so tool calls can require payment.
19+
20+
## Required inputs
21+
22+
- Client integrations need a signing account and one or more client payment methods.
23+
- Server integrations need a recipient, currency, amount, and `MPP_SECRET_KEY`.
24+
- Tempo examples use chain ID `4217` unless a page explicitly covers Moderato testnet.
25+
- Stripe examples need a configured Stripe account and Shared Payment Token flow.
26+
- MCP integrations need the MCP client or server object to wrap.
27+
28+
## Constraints
29+
30+
- Keep `MPP_SECRET_KEY` server-side and out of logs.
31+
- Never commit private keys or wallet seeds.
32+
- Treat runtime `402` Challenges as authoritative for current payment terms.
33+
- Return `id` and `opaque` unchanged when responding to a Challenge.
34+
- Use `USDC.e` for Tempo bridged USDC examples, not generic USDC.
35+
1036
## Client
1137

1238
```ts
@@ -82,7 +108,9 @@ npx mppx example.com -v # verbose output
82108

83109
## References
84110

85-
- Docs: https://mpp.dev/sdk/typescript
86-
- Repo: https://github.com/wevm/mppx
87-
- Spec: https://github.com/tempoxyz/payment-auth-spec
88-
- Tempo: https://docs.tempo.xyz
111+
- [TypeScript SDK docs](https://mpp.dev/sdk/typescript)
112+
- [Client quickstart](https://mpp.dev/quickstart/client)
113+
- [Server quickstart](https://mpp.dev/quickstart/server)
114+
- [mppx repository](https://github.com/wevm/mppx)
115+
- [IETF Specification](https://paymentauth.org)
116+
- [Tempo docs](https://docs.tempo.xyz)

‎public/.well-known/api-catalog‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@
2424
"href": "https://mpp.dev/guides/building-with-an-llm",
2525
"title": "Build with an LLM",
2626
"type": "text/html"
27+
},
28+
{
29+
"href": "https://mpp.dev/AGENTS.md",
30+
"title": "Agent instructions",
31+
"type": "text/markdown"
2732
}
2833
],
2934
"status": [
@@ -38,6 +43,11 @@
3843
"href": "https://mpp.dev/.well-known/agent-skills/index.json",
3944
"title": "Agent Skills discovery index",
4045
"type": "application/json"
46+
},
47+
{
48+
"href": "https://mpp.dev/agent-permissions.json",
49+
"title": "Agent permissions",
50+
"type": "application/json"
4151
}
4252
]
4353
}

‎public/AGENTS.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# MPP documentation
2+
3+
Use this site to integrate MPP, the Machine Payments Protocol for HTTP `402` payment flows.
4+
5+
## Start here
6+
7+
- Read [`llms.txt`](https://mpp.dev/llms.txt) for a concise page index.
8+
- Read [`llms-full.txt`](https://mpp.dev/llms-full.txt) when you need the full documentation in one request.
9+
- Use [`/.well-known/mcp.json`](https://mpp.dev/.well-known/mcp.json) to connect to the MPP documentation MCP server.
10+
- Use [`/.well-known/agent-skills/index.json`](https://mpp.dev/.well-known/agent-skills/index.json) to discover agent skills.
11+
12+
## Main tasks
13+
14+
- Add payments to an API with [`mppx`](https://mpp.dev/quickstart/server).
15+
- Connect a coding agent to paid APIs with [`mppx`](https://mpp.dev/quickstart/agent).
16+
- Use the TypeScript SDK reference at [`/sdk/typescript`](https://mpp.dev/sdk/typescript).
17+
- Browse paid services at [`/services`](https://mpp.dev/services).
18+
19+
## Project structure
20+
21+
- Documentation pages live under `/assets/md/` as Markdown mirrors.
22+
- Agent skills live under `/.well-known/agent-skills/`.
23+
- API discovery files live under `/.well-known/` and `/api/`.
24+
- Service catalog files live under `/services/`.
25+
26+
## Protocol terms
27+
28+
MPP uses a Challenge, Credential, and Receipt flow:
29+
30+
- Servers return Challenges in `WWW-Authenticate`.
31+
- Clients return Credentials in `Authorization`.
32+
- Servers return Receipts in `Payment-Receipt`.
33+
34+
Prefer Tempo stablecoin examples unless a page is specifically about another payment method.

‎public/agent-permissions.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"$schema": "https://mpp.dev/schemas/agent-permissions.schema.json",
3+
"agentUserAgents": ["ChatGPT-User", "ClaudeBot", "GPTBot", "PerplexityBot"],
4+
"allowedActions": [
5+
"read-documentation",
6+
"read-discovery",
7+
"read-openapi",
8+
"read-skill"
9+
],
10+
"allowedPaths": [
11+
"/",
12+
"/.well-known/*",
13+
"/AGENTS.md",
14+
"/agent-permissions.json",
15+
"/api/api-catalog",
16+
"/api/openapi.json",
17+
"/assets/md/*",
18+
"/llms-full.txt",
19+
"/llms.txt",
20+
"/services/llms.txt"
21+
],
22+
"disallowedActions": ["execute-payment", "submit-credential", "write-data"],
23+
"humanRequiredActions": [
24+
"execute-payment",
25+
"send-transaction",
26+
"store-private-key"
27+
],
28+
"permissions": {
29+
"read": true,
30+
"write": false
31+
},
32+
"rateLimits": {
33+
"burst": 60,
34+
"period": "1m"
35+
}
36+
}

‎public/agent.html‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1" />
6+
<title>MPP agent index</title>
7+
<meta
8+
name="description"
9+
content="Agent-readable entry point for MPP docs, API discovery, skills, permissions, and Markdown source."
10+
/>
11+
<meta name="ai:page-type" content="agent-index" />
12+
<meta name="ai:token-count" content="1200" />
13+
<link rel="canonical" href="https://mpp.dev/agent.html" />
14+
</head>
15+
<body>
16+
<main>
17+
<article>
18+
<h1>MPP agent index</h1>
19+
<p>
20+
Use this page as the compact HTML entry point for agents integrating
21+
MPP, mppx, or HTTP 402 payment flows. It links to the canonical
22+
Markdown, skill, permissions, and API discovery documents.
23+
</p>
24+
25+
<section>
26+
<h2>Primary files</h2>
27+
<table>
28+
<thead>
29+
<tr>
30+
<th>File</th>
31+
<th>Purpose</th>
32+
</tr>
33+
</thead>
34+
<tbody>
35+
<tr>
36+
<td><a href="/llms.txt">llms.txt</a></td>
37+
<td>Short documentation index grouped for agent retrieval.</td>
38+
</tr>
39+
<tr>
40+
<td><a href="/llms-full.txt">llms-full.txt</a></td>
41+
<td>Complete Markdown corpus for long-context agents.</td>
42+
</tr>
43+
<tr>
44+
<td><a href="/AGENTS.md">AGENTS.md</a></td>
45+
<td>Project conventions, key files, and build commands.</td>
46+
</tr>
47+
<tr>
48+
<td><a href="/agent-permissions.json">agent-permissions.json</a></td>
49+
<td>Allowed interactions, human gates, and rate limits.</td>
50+
</tr>
51+
<tr>
52+
<td><a href="/.well-known/agent-skills/mppx/SKILL.md">mppx skill</a></td>
53+
<td>Capabilities, inputs, constraints, and references.</td>
54+
</tr>
55+
<tr>
56+
<td><a href="/.well-known/api-catalog">API catalog</a></td>
57+
<td>Linkset discovery for docs, OpenAPI, skills, and metadata.</td>
58+
</tr>
59+
</tbody>
60+
</table>
61+
</section>
62+
63+
<section>
64+
<h2>Recommended flow</h2>
65+
<p>
66+
Start with <a href="/llms.txt">llms.txt</a>, fetch the smallest
67+
Markdown page that answers the task, then use the skill and API
68+
catalog only when you need integration details or machine-readable
69+
endpoints.
70+
</p>
71+
<pre><code>curl https://mpp.dev/llms.txt
72+
curl https://mpp.dev/.well-known/agent-skills/mppx/SKILL.md
73+
curl https://mpp.dev/agent-permissions.json</code></pre>
74+
</section>
75+
76+
<section>
77+
<h2>Human-agent bridge</h2>
78+
<p>
79+
Documentation pages expose clean Markdown mirrors under
80+
<code>/assets/md/</code>. Use the Copy for AI control in the page UI
81+
or fetch the Markdown directly.
82+
</p>
83+
<button type="button" data-copy-ai="" aria-label="Copy for AI">
84+
Copy for AI
85+
</button>
86+
<button type="button" data-copy="" aria-label="Copy command">
87+
Copy command
88+
</button>
89+
<p>
90+
<a href="/assets/md/index.md">View homepage as Markdown</a>
91+
</p>
92+
</section>
93+
</article>
94+
</main>
95+
</body>
96+
</html>

‎skills/mppx/SKILL.md‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,32 @@ description: TypeScript SDK for the Payment HTTP Authentication Scheme. Handles
77

88
TypeScript SDK for the "Payment" HTTP Authentication Scheme. Full 402 flow: challenge → credential → receipt.
99

10+
## What I can accomplish
11+
12+
- Add `402` payment handling to a client with `Fetch.polyfill` or `Fetch.from`.
13+
- Protect HTTP routes with server-side MPP Challenges and Receipt responses.
14+
- Accept one-time Tempo stablecoin payments with `tempo.charge`.
15+
- Accept metered Tempo stablecoin payments with `tempo.session`.
16+
- Accept one-time card payments with `stripe.charge`.
17+
- Verify Credentials directly for custom transports or background workflows.
18+
- Wrap MCP clients and servers so tool calls can require payment.
19+
20+
## Required inputs
21+
22+
- Client integrations need a signing account and one or more client payment methods.
23+
- Server integrations need a recipient, currency, amount, and `MPP_SECRET_KEY`.
24+
- Tempo examples use chain ID `4217` unless a page explicitly covers Moderato testnet.
25+
- Stripe examples need a configured Stripe account and Shared Payment Token flow.
26+
- MCP integrations need the MCP client or server object to wrap.
27+
28+
## Constraints
29+
30+
- Keep `MPP_SECRET_KEY` server-side and out of logs.
31+
- Never commit private keys or wallet seeds.
32+
- Treat runtime `402` Challenges as authoritative for current payment terms.
33+
- Return `id` and `opaque` unchanged when responding to a Challenge.
34+
- Use `USDC.e` for Tempo bridged USDC examples, not generic USDC.
35+
1036
## Client
1137

1238
```ts
@@ -93,7 +119,9 @@ npx mppx example.com -v # verbose output
93119

94120
## References
95121

96-
- Docs: https://mpp.dev/sdk/typescript
97-
- Repo: https://github.com/wevm/mppx
98-
- Spec: https://github.com/tempoxyz/payment-auth-spec
99-
- Tempo: https://docs.tempo.xyz
122+
- [TypeScript SDK docs](https://mpp.dev/sdk/typescript)
123+
- [Client quickstart](https://mpp.dev/quickstart/client)
124+
- [Server quickstart](https://mpp.dev/quickstart/server)
125+
- [mppx repository](https://github.com/wevm/mppx)
126+
- [IETF Specification](https://paymentauth.org)
127+
- [Tempo docs](https://docs.tempo.xyz)

‎src/env.d.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,13 @@ declare module "*.svg?raw" {
55
const content: string;
66
export default content;
77
}
8+
9+
declare module "*.md?raw" {
10+
const content: string;
11+
export default content;
12+
}
13+
14+
declare module "*.json?raw" {
15+
const content: string;
16+
export default content;
17+
}

‎src/pages/_api/.well-known/agent-skills/mppx/SKILL.md.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import skill from "../../../../../../public/.well-known/agent-skills/mppx/SKILL.md?raw";
2+
3+
const headers = {
4+
"Access-Control-Allow-Origin": "*",
5+
"Cache-Control": "public, max-age=300",
6+
"Content-Type": "text/markdown; charset=utf-8",
7+
"X-Content-Type-Options": "nosniff",
8+
};
9+
10+
export function GET() {
11+
return new Response(skill, { headers });
12+
}
13+
14+
export function HEAD() {
15+
return new Response(null, { headers });
16+
}

‎src/pages/_api/.well-known/api-catalog.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export { GET, HEAD } from "../api/api-catalog";

0 commit comments

Comments
 (0)