kayg/calternal

Watch

Fork 0

Research: MCP server + skill discovery, llms.txt and other agent conventions for calternal #204

New issue

Open

opened 2026-09-26 16:08:52 +00:00 by kayg · 5 comments

kayg commented

2026-09-26 16:08:52 +00:00

Owner

A remote MCP server for calternal (DESIGN §41: an adapter over the same routes as CLI/API/WebMCP): current MCP spec version, remote transport (Streamable HTTP), auth (OAuth 2.1 + protected resource metadata / .well-known discovery), scoping to data-only agent tokens (§21), and how clients discover the server.
Skills: is there a standard way for a server/site to publish an agent 'skill' (e.g. Anthropic Agent Skills format SKILL.md, any .well-known endpoint or registry, MCP prompts/resources as the carrier, other vendors' equivalents)? What would a calternal skill contain and where would it live?
llms.txt / llms-full.txt (spec, adoption), AGENTS.md, .well-known/ai-plugin.json (status), OpenAPI discovery, robots/ai.txt directives, sitemap for docs, and anything newer in 2026.
Security implications of each (prompt injection via published content, data exposure, auth).
Deliver: the doc, a proposed issue list (one per recommended item) posted as a comment for Claude to file, and nothing built yet. The WebMCP research (docs/research/webmcp.md on job/webmcp, #160) is related: read it first.

Owner 2026-09-26: 'we also need to expose a skill for that MCP, is there a standardised endpoint for that? also what about llms.txt and other conventions?' Research only (with web search, primary sources, dates checked), written to docs/research/agent-conventions.md in ASD-STE100, with a recommendation per item: 1. A remote MCP server for calternal (DESIGN §41: an adapter over the same routes as CLI/API/WebMCP): current MCP spec version, remote transport (Streamable HTTP), auth (OAuth 2.1 + protected resource metadata / .well-known discovery), scoping to data-only agent tokens (§21), and how clients discover the server. 2. Skills: is there a standard way for a server/site to publish an agent 'skill' (e.g. Anthropic Agent Skills format SKILL.md, any .well-known endpoint or registry, MCP prompts/resources as the carrier, other vendors' equivalents)? What would a calternal skill contain and where would it live? 3. llms.txt / llms-full.txt (spec, adoption), AGENTS.md, .well-known/ai-plugin.json (status), OpenAPI discovery, robots/ai.txt directives, sitemap for docs, and anything newer in 2026. 4. Security implications of each (prompt injection via published content, data exposure, auth). Deliver: the doc, a proposed issue list (one per recommended item) posted as a comment for Claude to file, and nothing built yet. The WebMCP research (docs/research/webmcp.md on job/webmcp, #160) is related: read it first.

kayg commented

2026-09-26 16:10:09 +00:00

Author

Owner

Starting research on branch job/agent-conventions, based on dev at e976bff6c74b3131266b3baeb33ab318edccd46e. I read the required design and vocabulary docs and the WebMCP report from job/webmcp (#160). I will add only docs/research/agent-conventions.md and an issue comment with recommendations and proposed follow-up issues.

Starting research on branch `job/agent-conventions`, based on `dev` at `e976bff6c74b3131266b3baeb33ab318edccd46e`. I read the required design and vocabulary docs and the WebMCP report from `job/webmcp` (#160). I will add only `docs/research/agent-conventions.md` and an issue comment with recommendations and proposed follow-up issues.

kayg commented

2026-09-26 16:17:40 +00:00

Author

Owner

Research finding: the current MCP revision is 2026-07-28. It adds the stateless server/discover lifecycle; a remote server uses Streamable HTTP. The current authorization section requires OAuth 2.1 and Protected Resource Metadata (RFC 9728), with audience-bound access tokens. calternal must map that authorization to the existing data scope only, per DESIGN §21. Sources: https://modelcontextprotocol.io/specification/2026-07-28 and https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization

The MCP Skills extension (io.modelcontextprotocol/skills) is now final (SEP-2640 merged 2026-09-13). It uses skills/list, skills/get and MCP Resources to publish Agent Skills folders. It is an optional extension, and host support is still being implemented. Sources: https://modelcontextprotocol.io/extensions/skills/overview and https://github.com/modelcontextprotocol/ext-skills

There is no stable public MCP server URL discovery endpoint yet. MCP server/discover works after a client knows the endpoint. The official Registry is still in preview and excludes private servers. MCP Server Cards remain in review. Sources: https://modelcontextprotocol.io/registry/about and https://plan.modelcontextprotocol.io/seps

Research finding: the current MCP revision is `2026-07-28`. It adds the stateless `server/discover` lifecycle; a remote server uses Streamable HTTP. The current authorization section requires OAuth 2.1 and Protected Resource Metadata (RFC 9728), with audience-bound access tokens. calternal must map that authorization to the existing `data` scope only, per DESIGN §21. Sources: https://modelcontextprotocol.io/specification/2026-07-28 and https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization The MCP Skills extension (`io.modelcontextprotocol/skills`) is now final (SEP-2640 merged 2026-09-13). It uses `skills/list`, `skills/get` and MCP Resources to publish Agent Skills folders. It is an optional extension, and host support is still being implemented. Sources: https://modelcontextprotocol.io/extensions/skills/overview and https://github.com/modelcontextprotocol/ext-skills There is no stable public MCP server URL discovery endpoint yet. MCP `server/discover` works after a client knows the endpoint. The official Registry is still in preview and excludes private servers. MCP Server Cards remain in review. Sources: https://modelcontextprotocol.io/registry/about and https://plan.modelcontextprotocol.io/seps

kayg commented

2026-09-26 16:24:55 +00:00

Author

Owner

Additional finding: the IETF Datatracker lists ADP v1.1 as an individual Internet-Draft with no formal standing in the IETF standards process. It proposes DNS discovery and /.well-known/agent.json, and says IANA denied registration of the agent well-known URI. I added it to the report as a watch item, not an implementation dependency: https://datatracker.ietf.org/doc/draft-pro-adp-agent-discovery/

Additional finding: the IETF Datatracker lists ADP v1.1 as an individual Internet-Draft with no formal standing in the IETF standards process. It proposes DNS discovery and `/.well-known/agent.json`, and says IANA denied registration of the `agent` well-known URI. I added it to the report as a watch item, not an implementation dependency: https://datatracker.ietf.org/doc/draft-pro-adp-agent-discovery/

kayg commented

2026-09-26 16:27:28 +00:00

Author

Owner

Final report

Committed the research report to docs/research/agent-conventions.md in 88441ac1b0f106f28a4aff8b5ec5554c217ac19d on job/agent-conventions.

The report recommends a remote MCP adapter on the current 2026-07-28 Streamable HTTP revision, with OAuth 2.1 and RFC 9728 Protected Resource Metadata. Use audience-bound, data-scope tokens. Keep authorization and validation on the existing action routes. The current server/discover method does not discover a server URL. The MCP Registry does not support private servers, and MCP Server Cards remain a draft. The report also covers the final MCP Skills extension, OpenAPI discovery, AGENTS.md, llms.txt, the retired ai-plugin.json, robots directives, sitemaps, A2A, ADP, and the 2026 AI discovery drafts.

The report recommends the MCP Skills extension plus Resources as the remote carrier for an Agent Skill. It recommends one source at .agents/skills/calternal/SKILL.md; the Agent Skills format does not require that path. OpenAI imports skills from MCP as a static submission-time snapshot, and client support for the extension is still limited. Public discovery files should list public documentation only. Robots files, sitemaps, skills, and published API descriptions do not provide access control.

Proposed issue list

Add OAuth 2.1 authorization for remote MCP clients. Publish Protected Resource Metadata and authorization server discovery. Issue a separate data-scope token for each Installation.
Add a remote MCP adapter over existing action routes. Use Streamable HTTP for MCP 2026-07-28; implement server/discover; add older protocol support only for required clients.
Publish one calternal Agent Skill. Keep its source in .agents/skills/calternal, install it in Agent containers, and expose it with io.modelcontextprotocol/skills and Resources where clients support the extension.
Expose the generated OpenAPI 3.1 contract at a stable URL and advertise it with rel="service-desc".
Publish public agent documentation: llms.txt, Markdown page versions, and a sitemap for public product documentation. Do not add llms-full.txt without measured use.
Adopt AGENTS.md as the shared repository instruction source, with CLAUDE.md as a link or short supplement. Keep one maintained copy.

Do not file implementation issues for ai-plugin.json, robots-ai.txt, AI.TXT, AGENTS.TXT, /.well-known/ai, /.well-known/agent.json, or MCP Server Cards while they remain proposals or drafts.

Decisions for owner confirmation

DESIGN does not define remote MCP authorization ownership. The report assumes calternal issues an Installation-specific data-scope token and does not reuse the Agent container token.
DESIGN does not select a skill path. The report recommends .agents/skills/calternal/SKILL.md as the single source.
This checkout has CLAUDE.md and no tracked AGENTS.md. The report recommends AGENTS.md as the shared canonical file; the owner may keep CLAUDE.md canonical.
DESIGN selects OpenAPI 3.1. The report keeps 3.1 even though OpenAPI 3.2.1 is the latest published version. It recommends rel="service-desc" but leaves the exact public contract URL open.
No stable domain-to-MCP-endpoint discovery format is ready for a calternal dependency. The report recommends configured MCP URLs until a discovery format is stable.

Completion and gates

git merge dev output: Already up to date.

Cargo and web gates were not run because this is a research-only job and no code changed. No tests were run. cargo clean output: Removed 1 file, 356B total. There was no web build output to delete.

## Final report Committed the research report to `docs/research/agent-conventions.md` in `88441ac1b0f106f28a4aff8b5ec5554c217ac19d` on `job/agent-conventions`. The report recommends a remote MCP adapter on the current `2026-07-28` Streamable HTTP revision, with OAuth 2.1 and RFC 9728 Protected Resource Metadata. Use audience-bound, data-scope tokens. Keep authorization and validation on the existing action routes. The current `server/discover` method does not discover a server URL. The MCP Registry does not support private servers, and MCP Server Cards remain a draft. The report also covers the final MCP Skills extension, OpenAPI discovery, AGENTS.md, llms.txt, the retired `ai-plugin.json`, robots directives, sitemaps, A2A, ADP, and the 2026 AI discovery drafts. The report recommends the MCP Skills extension plus Resources as the remote carrier for an Agent Skill. It recommends one source at `.agents/skills/calternal/SKILL.md`; the Agent Skills format does not require that path. OpenAI imports skills from MCP as a static submission-time snapshot, and client support for the extension is still limited. Public discovery files should list public documentation only. Robots files, sitemaps, skills, and published API descriptions do not provide access control. ### Proposed issue list 1. Add OAuth 2.1 authorization for remote MCP clients. Publish Protected Resource Metadata and authorization server discovery. Issue a separate data-scope token for each Installation. 2. Add a remote MCP adapter over existing action routes. Use Streamable HTTP for MCP `2026-07-28`; implement `server/discover`; add older protocol support only for required clients. 3. Publish one calternal Agent Skill. Keep its source in `.agents/skills/calternal`, install it in Agent containers, and expose it with `io.modelcontextprotocol/skills` and Resources where clients support the extension. 4. Expose the generated OpenAPI 3.1 contract at a stable URL and advertise it with `rel="service-desc"`. 5. Publish public agent documentation: `llms.txt`, Markdown page versions, and a sitemap for public product documentation. Do not add `llms-full.txt` without measured use. 6. Adopt AGENTS.md as the shared repository instruction source, with CLAUDE.md as a link or short supplement. Keep one maintained copy. Do not file implementation issues for `ai-plugin.json`, `robots-ai.txt`, AI.TXT, AGENTS.TXT, `/.well-known/ai`, `/.well-known/agent.json`, or MCP Server Cards while they remain proposals or drafts. ### Decisions for owner confirmation - DESIGN does not define remote MCP authorization ownership. The report assumes calternal issues an Installation-specific data-scope token and does not reuse the Agent container token. - DESIGN does not select a skill path. The report recommends `.agents/skills/calternal/SKILL.md` as the single source. - This checkout has CLAUDE.md and no tracked AGENTS.md. The report recommends AGENTS.md as the shared canonical file; the owner may keep CLAUDE.md canonical. - DESIGN selects OpenAPI 3.1. The report keeps 3.1 even though OpenAPI 3.2.1 is the latest published version. It recommends `rel="service-desc"` but leaves the exact public contract URL open. - No stable domain-to-MCP-endpoint discovery format is ready for a calternal dependency. The report recommends configured MCP URLs until a discovery format is stable. ### Completion and gates `git merge dev` output: `Already up to date.` Cargo and web gates were not run because this is a research-only job and no code changed. No tests were run. `cargo clean` output: `Removed 1 file, 356B total`. There was no web build output to delete.

kayg referenced this issue

2026-09-28 23:58:11 +00:00

MCP: calternal MCP server (remote, over HTTPS) — thin adapter over the HTTP API, scoped app passwords #329

kayg commented

2026-10-01 05:13:02 +00:00

Author

Owner

Hygiene review: the report is on job/agent-conventions at 88441ac1b0f106f28a4aff8b5ec5554c217ac19d, which is not in origin/dev. Preserving the unmerged research work and keeping #204 open.

Hygiene review: the report is on `job/agent-conventions` at `88441ac1b0f106f28a4aff8b5ec5554c217ac19d`, which is not in `origin/dev`. Preserving the unmerged research work and keeping #204 open.

kayg referenced this issue

2026-10-01 05:26:06 +00:00

HYGIENE: delete merged branches/worktrees, close done issues, gc (no history rewrite) #548

kayg referenced this issue

2026-10-02 13:23:05 +00:00

P2: Complete MCP output, errors, discovery and remote sign-in interoperability #836

kayg referenced this issue

2026-10-02 17:42:29 +00:00

Audit: open issue hygiene (duplicates, already fixed, stale) #866

kayg referenced this issue

2026-10-03 12:56:40 +00:00

Issue hygiene sweep 2026-10-03 #1008