-
Notifications
You must be signed in to change notification settings - Fork 136
docs: improve agentic discovery score #779
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+476
−12
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # MPP documentation | ||
|
|
||
| Use this site to integrate MPP, the Machine Payments Protocol for HTTP `402` payment flows. | ||
|
|
||
| ## Start here | ||
|
|
||
| - Read [`llms.txt`](https://mpp.dev/llms.txt) for a concise page index. | ||
| - Read [`llms-full.txt`](https://mpp.dev/llms-full.txt) when you need the full documentation in one request. | ||
| - Use [`/.well-known/mcp.json`](https://mpp.dev/.well-known/mcp.json) to connect to the MPP documentation MCP server. | ||
| - Use [`/.well-known/agent-skills/index.json`](https://mpp.dev/.well-known/agent-skills/index.json) to discover agent skills. | ||
|
|
||
| ## Main tasks | ||
|
|
||
| - Add payments to an API with [`mppx`](https://mpp.dev/quickstart/server). | ||
| - Connect a coding agent to paid APIs with [`mppx`](https://mpp.dev/quickstart/agent). | ||
| - Use the TypeScript SDK reference at [`/sdk/typescript`](https://mpp.dev/sdk/typescript). | ||
| - Browse paid services at [`/services`](https://mpp.dev/services). | ||
|
|
||
| ## Project structure | ||
|
|
||
| - Documentation pages live under `/assets/md/` as Markdown mirrors. | ||
| - Agent skills live under `/.well-known/agent-skills/`. | ||
| - API discovery files live under `/.well-known/` and `/api/`. | ||
| - Service catalog files live under `/services/`. | ||
|
|
||
| ## Protocol terms | ||
|
|
||
| MPP uses a Challenge, Credential, and Receipt flow: | ||
|
|
||
| - Servers return Challenges in `WWW-Authenticate`. | ||
| - Clients return Credentials in `Authorization`. | ||
| - Servers return Receipts in `Payment-Receipt`. | ||
|
|
||
| Prefer Tempo stablecoin examples unless a page is specifically about another payment method. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| { | ||
| "$schema": "https://mpp.dev/schemas/agent-permissions.schema.json", | ||
| "agentUserAgents": ["ChatGPT-User", "ClaudeBot", "GPTBot", "PerplexityBot"], | ||
| "allowedActions": [ | ||
| "read-documentation", | ||
| "read-discovery", | ||
| "read-openapi", | ||
| "read-skill" | ||
| ], | ||
| "allowedPaths": [ | ||
| "/", | ||
| "/.well-known/*", | ||
| "/AGENTS.md", | ||
| "/agent-permissions.json", | ||
| "/api/api-catalog", | ||
| "/api/openapi.json", | ||
| "/assets/md/*", | ||
| "/llms-full.txt", | ||
| "/llms.txt", | ||
| "/services/llms.txt" | ||
| ], | ||
| "disallowedActions": ["execute-payment", "submit-credential", "write-data"], | ||
| "humanRequiredActions": [ | ||
| "execute-payment", | ||
| "send-transaction", | ||
| "store-private-key" | ||
| ], | ||
| "permissions": { | ||
| "read": true, | ||
| "write": false | ||
| }, | ||
| "rateLimits": { | ||
| "burst": 60, | ||
| "period": "1m" | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8" /> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | ||
| <title>MPP agent index</title> | ||
| <meta | ||
| name="description" | ||
| content="Agent-readable entry point for MPP docs, API discovery, skills, permissions, and Markdown source." | ||
| /> | ||
| <meta name="ai:page-type" content="agent-index" /> | ||
| <meta name="ai:token-count" content="1200" /> | ||
| <link rel="canonical" href="https://mpp.dev/agent.html" /> | ||
| </head> | ||
| <body> | ||
| <main> | ||
| <article> | ||
| <h1>MPP agent index</h1> | ||
| <p> | ||
| Use this page as the compact HTML entry point for agents integrating | ||
| MPP, mppx, or HTTP 402 payment flows. It links to the canonical | ||
| Markdown, skill, permissions, and API discovery documents. | ||
| </p> | ||
|
|
||
| <section> | ||
| <h2>Primary files</h2> | ||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>File</th> | ||
| <th>Purpose</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><a href="/llms.txt">llms.txt</a></td> | ||
| <td>Short documentation index grouped for agent retrieval.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><a href="/llms-full.txt">llms-full.txt</a></td> | ||
| <td>Complete Markdown corpus for long-context agents.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><a href="/AGENTS.md">AGENTS.md</a></td> | ||
| <td>Project conventions, key files, and build commands.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><a href="/agent-permissions.json">agent-permissions.json</a></td> | ||
| <td>Allowed interactions, human gates, and rate limits.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><a href="/.well-known/agent-skills/mppx/SKILL.md">mppx skill</a></td> | ||
| <td>Capabilities, inputs, constraints, and references.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><a href="/.well-known/api-catalog">API catalog</a></td> | ||
| <td>Linkset discovery for docs, OpenAPI, skills, and metadata.</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
| </section> | ||
|
|
||
| <section> | ||
| <h2>Recommended flow</h2> | ||
| <p> | ||
| Start with <a href="/llms.txt">llms.txt</a>, fetch the smallest | ||
| Markdown page that answers the task, then use the skill and API | ||
| catalog only when you need integration details or machine-readable | ||
| endpoints. | ||
| </p> | ||
| <pre><code>curl https://mpp.dev/llms.txt | ||
| curl https://mpp.dev/.well-known/agent-skills/mppx/SKILL.md | ||
| curl https://mpp.dev/agent-permissions.json</code></pre> | ||
| </section> | ||
|
|
||
| <section> | ||
| <h2>Human-agent bridge</h2> | ||
| <p> | ||
| Documentation pages expose clean Markdown mirrors under | ||
| <code>/assets/md/</code>. Use the Copy for AI control in the page UI | ||
| or fetch the Markdown directly. | ||
| </p> | ||
| <button type="button" data-copy-ai="" aria-label="Copy for AI"> | ||
| Copy for AI | ||
| </button> | ||
| <button type="button" data-copy="" aria-label="Copy command"> | ||
| Copy command | ||
| </button> | ||
| <p> | ||
| <a href="/assets/md/index.md">View homepage as Markdown</a> | ||
| </p> | ||
| </section> | ||
| </article> | ||
| </main> | ||
| </body> | ||
| </html> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| import skill from "../../../../../../public/.well-known/agent-skills/mppx/SKILL.md?raw"; | ||
|
|
||
| const headers = { | ||
| "Access-Control-Allow-Origin": "*", | ||
| "Cache-Control": "public, max-age=300", | ||
| "Content-Type": "text/markdown; charset=utf-8", | ||
| "X-Content-Type-Options": "nosniff", | ||
| }; | ||
|
|
||
| export function GET() { | ||
| return new Response(skill, { headers }); | ||
| } | ||
|
|
||
| export function HEAD() { | ||
| return new Response(null, { headers }); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| export { GET, HEAD } from "../api/api-catalog"; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| import agents from "../../../public/AGENTS.md?raw"; | ||
|
|
||
| const headers = { | ||
| "Access-Control-Allow-Origin": "*", | ||
| "Cache-Control": "public, max-age=300", | ||
| "Content-Type": "text/markdown; charset=utf-8", | ||
| "X-Content-Type-Options": "nosniff", | ||
| }; | ||
|
|
||
| export function GET() { | ||
| return new Response(agents, { headers }); | ||
| } | ||
|
|
||
| export function HEAD() { | ||
| return new Response(null, { headers }); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| import permissions from "../../../public/agent-permissions.json?raw"; | ||
|
|
||
| const headers = { | ||
| "Access-Control-Allow-Origin": "*", | ||
| "Cache-Control": "public, max-age=300", | ||
| "Content-Type": "application/json; charset=utf-8", | ||
| "X-Content-Type-Options": "nosniff", | ||
| }; | ||
|
|
||
| export function GET() { | ||
| return new Response(permissions, { headers }); | ||
| } | ||
|
|
||
| export function HEAD() { | ||
| return new Response(null, { headers }); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The new agent index and API catalog advertise
/AGENTS.mdand/agent-permissions.jsonas primary agent-readable discovery files, but this allowlist only permits/,/.well-known/*, API docs, markdown mirrors, and llms files. If an agent enforcesallowedPathsafter reading this policy, the advertised instructions and permission document fall outside the allowed read surface, which self-blocks the discovery flow this file is meant to enable.Useful? React with 👍 / 👎.