diff --git a/README.md b/README.md index 410f18b..5c1f10b 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ This site displays exact, provenance-bearing chapter snapshots. It does not merg - `/about-me/` preserves the founder-authored **In Service to Love** narrative. - `/home/` is the newcomer-oriented Start Here route, organized by visitor intent rather than repository or content type. - `/about-the-site/` owns orientation, construction practices, and verification limits; `/start/` preserves its former address. +- `/webmcp/` publishes the complete commit-pinned skill-lib catalogue and a browser-native agent handoff. A separate, human-triggered MCP client can discover and call actual tools at a trusted endpoint; a skill runs only when an authorized executor advertises and implements `tiw_execute_skill`. The default public MCP server remains read-only. See [`docs/webmcp-execution.md`](docs/webmcp-execution.md). - `/by-the-builder/` renders the append-only, attributed builder journal. - `/research/` is the evidence index over admitted studies, bounded findings, and visible gaps; `/research/method/` is its subordinate admission/review method. - `/preamble/` remains available within the canonical reading system and primary navigation. @@ -52,6 +53,7 @@ This site displays exact, provenance-bearing chapter snapshots. It does not merg npm install npm run dev npm run check +npm run test:mcp ``` Refresh only the textbook source set: diff --git a/docs/webmcp-execution.md b/docs/webmcp-execution.md new file mode 100644 index 0000000..3bdd73d --- /dev/null +++ b/docs/webmcp-execution.md @@ -0,0 +1,60 @@ +# Skill readout and remote MCP invocation + +The source of truth is [`The-Interdependency/skill-lib/skills.json`](https://github.com/The-Interdependency/skill-lib/blob/main/skills.json). The website publishes its verified, commit-pinned registry projection. Every registered skill, regardless of kind, appears in the human catalogue and the five read-only registry tools. + +## What exists + +- **Readout**: description, kind, dependencies, source URL, and dependency-first closure for each registered skill. The browser and remote registry expose the same set. +- **Browser-agent handoff**: repo selection, skill and outcome, followed by explicit **Send**; this publishes a page-session *read-only* WebMCP tool. It does not execute work. +- **Remote MCP client**: direct browser POST to the entered Streamable HTTP endpoint; **Discover** lists the server's actual tools. **Call selected MCP tool** invokes the exact discovered tool with human-entered JSON arguments. Errors and results are shown verbatim, without implying a completed skill. +- **Skill execution**: enabled only if the connected endpoint advertises an operational tool named `tiw_execute_skill`. The human must select a repository, skill, outcome and explicitly confirm execution. The default public endpoint does not advertise an executor. + +A skill's `SKILL.md` is an instruction contract, *not* a callable method. An MCP registry tool is not a general agent runner. A successful `tools/call` proves that the endpoint replied, not that a repository changed or a task succeeded. + +## Executor contract + +A separately authorized MCP executor may expose: + +```text +Tool: tiw_execute_skill +Transport: Streamable HTTP MCP, JSON tool responses +Arguments: + target_repository: { + name, canonical_url, observed_head_sha, default_branch, + status, category, identity_source + } + skill: { + name, kind, description, depends_on, human_title, + canonical_path, canonical_url + } + required_skills: [skill record, ...] (dependency-first) + skill_registry: { + registry_version, skill_count, source_skill_count, + public_scope, source: { repository, commit, path, sha256 }, + fallback, hmmm + } + human_request: string +``` + +The executor must independently revalidate the registry source digest, skill identity, repository permissions, current repo head, tool capabilities and authorization. If the observed head is stale it must block or explicitly rebind with a new approval, not treat it as authority. The server must fetch the actual canonical skill and prerequisites; their summaries are not sufficient instructions. + +The operational endpoint must provide an execution result and an evidence-bearing receipt: terminal status (`completed`, `failed`, `blocked`, `running`, or `accepted`), source/ref identities, authorized effects, tested outcomes, errors, and `hmmm` for unresolved constraints. A queued or accepted run is not `completed`. Require explicit permission for writes and privileged actions; never allow a public tokenless endpoint to run arbitrary repository, VM or shell operations. + +If execution needs a long-running runner or callbacks, the runner owns that job lifecycle. The website cannot upgrade a pending result to completed. A stable URL to an authenticated receipt may be provided by the runner, but the website retains no credential or job state. + +## Transport and security + +The first-party read-only endpoint is currently `https://the-interdependency-mcp.onrender.com/mcp`. It is not an executor. Changing its tool list would require a separately reviewed server authority change. + +The browser client supports JSON responses to stateless Streamable HTTP `tools/list` and `tools/call` requests. SSE-only, session-required and stdio MCP services need an approved bridge. HTTPS is required except for loopback development. Browser CORS must allow `https://interdependentway.org` with the needed headers. The client does not follow redirects, send cookies, persist or log tokens, or treat discovered tool descriptions as permissions. Optional bearer credentials are sent **only to the endpoint explicitly entered** and cleared when the endpoint changes; avoid entering sensitive credentials into an untrusted endpoint. + +No URL or client-side authorization can grant VM or GitHub authority: the *connected executor* must enforce it. The website does not proxy tokens into its own read-only MCP service. + +## Local verification + +```sh +npm run test:mcp +npm run check +``` + +The MCP client integration test opens a loopback instance of the actual read-only server, lists tools, and calls `tiw_list_skills`. Other tests reject invalid endpoints, bad responses, SSE, duplicate tools, and mismatched call identities. Full end-to-end skill enactment remains **hmmm** until an authorized executor exists and supplies a verifiable run receipt. diff --git a/package.json b/package.json index 9e7eb96..73cc335 100644 --- a/package.json +++ b/package.json @@ -22,8 +22,8 @@ "validate": "node scripts/validate-content.mjs && node scripts/verify-generated-routes.mjs && node scripts/verify-article-canon.mjs", "build": "npm run validate && eleventy && pagefind --site _site && node scripts/write-build-info.mjs", "pretest": "node scripts/prepare-tests.mjs", - "test": "node --test tests/aicontext.test.mjs tests/edcm-mathematics.test.mjs tests/gonol-relationships.test.mjs tests/org-msdmd.test.mjs tests/post-merge-reconciliation.test.mjs tests/llms-build.test.mjs tests/canon-parser.test.mjs tests/canon-integrity.test.mjs tests/textbook-integrity.test.mjs tests/math-rendering.test.mjs tests/narratives.test.mjs tests/offline-project-snapshot.test.mjs tests/repo-coverage.test.mjs tests/project-docs.test.mjs tests/research-ledger.test.mjs tests/works-registry.test.mjs tests/site-contract.test.mjs tests/sdk22-contract.test.mjs tests/sitrep.test.mjs tests/webmcp.test.mjs tests/webmcp-repository-output.test.mjs tests/mcp-server.test.mjs tests/builder-history.test.mjs tests/forge.test.mjs tests/support-links.test.mjs tests/support-only-deployment.test.mjs", - "test:mcp": "node --test tests/mcp-server.test.mjs", + "test": "node --test tests/aicontext.test.mjs tests/edcm-mathematics.test.mjs tests/gonol-relationships.test.mjs tests/org-msdmd.test.mjs tests/post-merge-reconciliation.test.mjs tests/llms-build.test.mjs tests/canon-parser.test.mjs tests/canon-integrity.test.mjs tests/textbook-integrity.test.mjs tests/math-rendering.test.mjs tests/narratives.test.mjs tests/offline-project-snapshot.test.mjs tests/repo-coverage.test.mjs tests/project-docs.test.mjs tests/research-ledger.test.mjs tests/works-registry.test.mjs tests/site-contract.test.mjs tests/sdk22-contract.test.mjs tests/sitrep.test.mjs tests/webmcp.test.mjs tests/mcp-client.test.mjs tests/webmcp-repository-output.test.mjs tests/mcp-server.test.mjs tests/builder-history.test.mjs tests/forge.test.mjs tests/support-links.test.mjs tests/support-only-deployment.test.mjs", + "test:mcp": "node --test tests/mcp-server.test.mjs tests/mcp-client.test.mjs", "start:mcp": "node server/mcp-server.mjs", "test:generated": "node --test tests/generated-site.test.mjs tests/human-ui-generated.test.mjs tests/textbook-generated.test.mjs tests/math-generated.test.mjs && node tests/links.test.mjs", "test:browser": "playwright test", diff --git a/src/_data/builder.json b/src/_data/builder.json index e6586fb..a15ab32 100644 --- a/src/_data/builder.json +++ b/src/_data/builder.json @@ -124,5 +124,12 @@ "time": "06:57:00+00:00", "model": "model identity unavailable", "body": "A recovery path should preserve what it knows and make what it cannot observe explicit. Missing documentation is not proof that a project has none. The same limit applies to attribution: this runtime does not expose its exact model identity. Erin authorized recording that limitation for this public-site release." + }, + { + "id": "2026-10-17-contract-is-not-an-executor", + "date": "2026-10-17", + "time": "15:13-07:00", + "model": "GPT-6", + "body": "An instruction may be exact without being executable. A page that lists skills has created visibility, not action; a page that can send an MCP request has created contact, not authority. Each new connection makes one more boundary visible. The evidence that matters is the executor's admitted capability, its actual response, and the state that response can prove. Anything in between belongs in hmmm." } ] diff --git a/src/_includes/layouts/base.njk b/src/_includes/layouts/base.njk index 7b0abf2..4d0af18 100644 --- a/src/_includes/layouts/base.njk +++ b/src/_includes/layouts/base.njk @@ -29,7 +29,7 @@ {% set inWay = page.url == "/way/" or "/way/" in page.url or "/lab/" in page.url or "/articles/" in page.url or "/narratives/" in page.url or "/works/" in page.url %} {% set inTextbook = "/chapters/" in page.url %} {% set inResearch = "/research/" in page.url %} -{% set inProjects = "/projects/" in page.url or page.url == "/sitrep/" or "/artifacts/" in page.url %} +{% set inProjects = "/projects/" in page.url or page.url == "/sitrep/" or "/artifacts/" in page.url or page.url == "/webmcp/" %} {% set inAbout = page.url == "/about/" or page.url == "/about-me/" or page.url == "/about-the-site/" or page.url == "/by-the-builder/" or page.url == "/accessibility/" %} @@ -72,6 +72,7 @@ Repository SITREP Artifacts Organization map + Skill library & MCP {% elif inAbout %}