@openship/protocol 0.0.1 → 0.0.2

package/README.md

@@ -2,6 +2,9 @@
 
 Canonical OpenShip 1.0 types, validators, source digest/diff helpers, selector matching, safe path/base64 utilities, browser discovery retrieval, and skill synchronization.
 
+The package also exports the standard OpenShip Sources MCP tool/resource names and tool input types;
+it deliberately does not depend on an MCP SDK.
+
 ```js
 import { fetchOpenShip, validateSystems } from "@openship/protocol";
 

package/dist/package-meta.json

@@ -1,7 +1,7 @@
 {
   "openship": "1.0",
   "package": "@openship/protocol",
-  "packageVersion": "0.0.1",
+  "packageVersion": "0.0.2",
   "source": "https://github.com/openshipdev/openship/tree/main/skills/openship",
-  "sourceCommit": "40e94cc1a5c7eb06787d22257df63785052c9124"
+  "sourceCommit": "9d6c35e78bae95a368220beea241a214aa0f24f3"
 }

package/dist/skill/SKILL.md

@@ -11,8 +11,8 @@ Read only the references needed for the task:
 
 - For the protocol overview, discovery, shared conventions, or capability selection, read [references/openship.md](references/openship.md).
 - For publishing, retrieving, or validating a source snapshot, read [references/openship-sources.md](references/openship-sources.md).
+- For exposing or consuming Sources through MCP, also read [references/openship-mcp.md](references/openship-mcp.md).
 - For proposing or serving candidate code versions, read both [references/openship-sources.md](references/openship-sources.md) and [references/openship-changes.md](references/openship-changes.md).
 - For authoring or consuming a self-contained architecture and source payload, read both [references/openship-sources.md](references/openship-sources.md) and [references/openship-systems.md](references/openship-systems.md).
 
 Machine-readable schemas and conformance examples are under [references/schemas](references/schemas) and [references/examples](references/examples). Treat the Markdown specifications as normative when a constraint cannot be expressed by JSON Schema.
-

package/dist/skill/references/examples/invalid/discovery-mcp.json

@@ -0,0 +1,12 @@
+{
+  "openship": "1.0",
+  "capability": "discovery",
+  "project": { "name": "Broken MCP", "description": "The MCP URL is not absolute HTTPS." },
+  "capabilities": {
+    "sources": {
+      "manifest": "https://example.com/openship/manifest.json",
+      "bundle": "https://example.com/openship/bundle.json",
+      "mcp": "/mcp"
+    }
+  }
+}

package/dist/skill/references/examples/valid/discovery.json

@@ -7,6 +7,7 @@
     "sources": {
       "manifest": "https://example.com/openship/manifest.json",
       "bundle": "https://example.com/openship/bundle.json",
+      "mcp": "https://mcp.example.com/mcp",
       "file": "https://example.com/openship/file/{path}",
       "archive": "https://example.com/openship/source.tar.gz"
     },
@@ -17,4 +18,3 @@
     }
   }
 }
-

package/dist/skill/references/openship-mcp.md

@@ -0,0 +1,52 @@
+# OpenShip Sources MCP binding
+
+Status: Draft v1  
+Protocol version: `1.0`
+
+This optional binding lets an MCP server expose one OpenShip Sources snapshot without replacing the normative HTTP discovery, Manifest, or Bundle representations. Read [openship.md](openship.md) and [openship-sources.md](openship-sources.md) first.
+
+## Discovery
+
+A producer MAY advertise an absolute HTTPS Streamable HTTP endpoint as `capabilities.sources.mcp`:
+
+```json
+{
+  "capabilities": {
+    "sources": {
+      "manifest": "https://example.com/openship/manifest.json",
+      "bundle": "https://example.com/openship/bundle.json",
+      "mcp": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+The MCP binding MUST expose the same current Sources snapshot as the advertised HTTP Manifest and Bundle. It MUST NOT require authentication. An MCP endpoint MAY expose unrelated authenticated tools alongside OpenShip, but authentication failures for those tools MUST NOT prevent OpenShip source reads.
+
+## Tool
+
+The server MUST register one tool named `openship` with this input union:
+
+```json
+{ "operation": "manifest" }
+{ "operation": "read", "path": "app/page.tsx" }
+```
+
+`manifest` returns the configured OpenShip origin and its complete validated Sources Manifest. `read` accepts one exact safe Manifest path and returns the snapshot digest, file metadata, declared encoding, and content. UTF-8 content is text; binary content is canonical base64. The tool MUST NOT resolve arbitrary filesystem or URL paths.
+
+The binding does not define a whole-Bundle tool. A client retrieves only the files it needs and verifies their metadata against the returned Manifest.
+
+## Resources
+
+Resource-aware servers SHOULD also expose:
+
+- `openship://sources/manifest` with the Manifest as `application/json` text.
+- `openship://sources/file{?path}` as a resource template and enumerate its concrete Manifest files from `resources/list`.
+
+UTF-8 files use MCP text contents. Base64 files use MCP blob contents with the Manifest media type. A concrete file URI percent-encodes the complete repository path in the `path` query parameter.
+
+## Integrity and errors
+
+The server MUST validate the Manifest and every Bundle byte before returning source content. A changed Manifest digest requires a newly validated Bundle; an invalid or incomplete replacement MUST NOT displace the last complete cache entry or be returned as current source. Unknown and unsafe paths fail without content.
+
+Implementations MAY impose a decoded-size limit and SHOULD report machine-readable failures for invalid paths, missing files, unavailable origins, invalid snapshots, and snapshots exceeding that limit.

package/dist/skill/references/openship-sources.md

@@ -6,18 +6,22 @@ Read [openship.md](openship.md) first for discovery, transport, and caching rule
 
 ## Endpoints
 
-Discovery advertises two required and three optional URLs:
+Discovery advertises two required and four optional URLs:
 
 | Link | Required | Meaning |
 |---|---:|---|
 | `manifest` | Yes | Project identity and file metadata, without content. |
 | `bundle` | Yes | Every file's encoded content in one JSON document. |
+| `mcp` | No | A public MCP endpoint implementing the OpenShip Sources binding. |
 | `file` | No | Raw content for one manifest path. |
 | `archive` | No | The manifest file set as a compressed archive. |
 | `instructions` | No | Plain-language project-specific retrieval guidance. |
 
 All reads are public, CORS-readable GET requests.
 
+See [openship-mcp.md](openship-mcp.md) when `mcp` is advertised. The HTTP Manifest and Bundle
+remain normative and required.
+
 ## Manifest
 
 ```json
@@ -140,4 +144,3 @@ A consumer MUST finish validation before executing any retrieved code.
 ## Security
 
 Serving Sources makes every included byte public. Producers MUST NOT publish secrets, environment values, signing keys, private deployment configuration, or data exports. File selection is the primary security boundary; filters and pattern scans are defense in depth.
-

package/dist/skill/references/openship.md

@@ -61,6 +61,7 @@ The response MUST be unauthenticated JSON, MUST allow cross-origin reads with `A
     "sources": {
       "manifest": "https://example.com/openship/manifest.json",
       "bundle": "https://example.com/openship/bundle.json",
+      "mcp": "https://mcp.example.com/mcp",
       "file": "https://example.com/openship/file/{path}",
       "archive": "https://example.com/openship/source.tar.gz",
       "instructions": "https://example.com/openship/agent.txt"
@@ -82,6 +83,7 @@ Requirements:
 - `project`, `capabilities`, and `capabilities.sources` are REQUIRED.
 - `project.name` and `project.description` are REQUIRED.
 - `sources.manifest` and `sources.bundle` are REQUIRED.
+- `sources.mcp` is OPTIONAL and, when present, advertises the OpenShip Sources MCP binding.
 - `changes`, `systems`, and `skill` are OPTIONAL and MUST be omitted when unavailable.
 - Changes MUST NOT be advertised without Sources.
 - `file` and `status` are URI templates with exactly the named expansion.
@@ -114,6 +116,7 @@ Changes status responses change over time and MUST use `Cache-Control: no-store`
 ## Capability documents
 
 - Read [openship-sources.md](openship-sources.md) for source snapshots and integrity.
+- Read [openship-mcp.md](openship-mcp.md) for the optional MCP binding for Sources.
 - Read [openship-changes.md](openship-changes.md) for candidate changes and isolation.
 - Read [openship-systems.md](openship-systems.md) for the self-contained systems model.
 
@@ -122,4 +125,3 @@ Changes status responses change over time and MUST use `Cache-Control: no-store`
 A producer is conformant for a capability when its advertised documents pass the relevant schema and every cross-document invariant in that capability specification. Advertising one capability does not claim conformance for another.
 
 A consumer SHOULD report a precise path and invariant when rejecting a payload. It MUST reject unsupported major versions rather than silently interpreting them as v1.
-

package/dist/skill/references/schemas/discovery.schema.json

@@ -27,6 +27,7 @@
           "properties": {
             "manifest": { "$ref": "#/$defs/httpsUrl" },
             "bundle": { "$ref": "#/$defs/httpsUrl" },
+            "mcp": { "$ref": "#/$defs/httpsUrl" },
             "file": { "type": "string", "pattern": "^https://.+\\{path\\}.+$|^https://.+/\\{path\\}$" },
             "archive": { "$ref": "#/$defs/httpsUrl" },
             "instructions": { "$ref": "#/$defs/httpsUrl" }
@@ -58,4 +59,3 @@
   },
   "additionalProperties": true
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openship/protocol",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Canonical OpenShip 1.0 types, validators, consumer helpers, schemas, and skill assets.",
   "type": "module",
   "license": "MIT",

package/src/index.d.ts

@@ -1,9 +1,14 @@
 export type OpenShipEncoding = "utf-8" | "base64";
 export type OpenShipCapability = "discovery" | "sources" | "changes" | "systems";
+export type OpenShipMcpOperation = "manifest" | "read";
+export type OpenShipMcpInput = { operation: "manifest" } | { operation: "read"; path: string };
+export const OPENSHIP_MCP_TOOL_NAME: "openship";
+export const OPENSHIP_MCP_MANIFEST_RESOURCE_URI: "openship://sources/manifest";
+export const OPENSHIP_MCP_FILE_RESOURCE_TEMPLATE: "openship://sources/file{?path}";
 export interface SourceFileMetadata { path: string; size: number; sha256: string; encoding: OpenShipEncoding; mediaType: string; type: "file" | "symlink"; target?: string; [key: string]: unknown }
 export interface SourcesManifest { openship: "1.0"; capability: "sources"; digest: string; project: { name: string; description: string; [key: string]: unknown }; totals: { files: number; bytes: number; [key: string]: unknown }; files: SourceFileMetadata[]; [key: string]: unknown }
 export interface SourcesBundle { openship: "1.0"; capability: "sources"; digest: string; files: Record<string, { encoding: OpenShipEncoding; content: string; [key: string]: unknown }>; [key: string]: unknown }
-export interface DiscoveryDocument { openship: "1.0"; capability: "discovery"; project: { name: string; description: string; [key: string]: unknown }; capabilities: { sources: { manifest: string; bundle: string; [key: string]: unknown }; systems?: { document: string; [key: string]: unknown }; changes?: { policy: string; submit: string; status: string; [key: string]: unknown }; [key: string]: unknown }; [key: string]: unknown }
+export interface DiscoveryDocument { openship: "1.0"; capability: "discovery"; project: { name: string; description: string; [key: string]: unknown }; capabilities: { sources: { manifest: string; bundle: string; mcp?: string; [key: string]: unknown }; systems?: { document: string; [key: string]: unknown }; changes?: { policy: string; submit: string; status: string; [key: string]: unknown }; [key: string]: unknown }; [key: string]: unknown }
 export type SystemsNodeKind = "Root" | "Host" | "Container" | "Process" | "Library";
 export type SystemsNodeOwnership = "first_party" | "third_party";
 export interface SystemsNodeMetadata { ownership: SystemsNodeOwnership; [key: string]: unknown }
@@ -22,6 +27,7 @@ export function compareUtf8(left: string, right: string): number;
 export function matchOpenShipPattern(pattern: string, path: string): boolean;
 export function computeSourcesDigest(files: SourceFileMetadata[]): string;
 export function validateDiscovery(value: unknown): DiscoveryDocument;
+export function validateSourcesManifest(value: unknown): SourcesManifest;
 export function validateSources(manifest: unknown, bundle: unknown, options?: { maxDecodedBytes?: number }): VerifiedSources;
 export function validateSystems(value: unknown, options?: { maxDecodedBytes?: number }): SystemsDocument;
 export function validateChangesDocument(value: unknown): Record<string, unknown>;

package/src/index.js

@@ -6,6 +6,10 @@ const digestPattern = /^sha256:[0-9a-f]{64}$/;
 const hexPattern = /^[0-9a-f]{64}$/;
 const idPattern = /^[A-Za-z0-9._:-]+$/;
 
+export const OPENSHIP_MCP_TOOL_NAME = "openship";
+export const OPENSHIP_MCP_MANIFEST_RESOURCE_URI = "openship://sources/manifest";
+export const OPENSHIP_MCP_FILE_RESOURCE_TEMPLATE = "openship://sources/file{?path}";
+
 export class OpenShipValidationError extends Error {
   constructor(path, message, code = "invalid_openship") {
     super(`${path}: ${message}`);
@@ -121,7 +125,7 @@ function decodeBundleEntry(entry, path) {
   return bytes;
 }
 
-function validateManifest(value) {
+export function validateSourcesManifest(value) {
   const manifest = envelope(value, "sources");
   if (!digestPattern.test(manifest.digest)) fail("$.digest", "must be a sha256 digest");
   const project = object(manifest.project, "$.project");
@@ -151,7 +155,7 @@ function validateManifest(value) {
 }
 
 export function validateSources(manifestValue, bundleValue, options = {}) {
-  const manifest = validateManifest(manifestValue);
+  const manifest = validateSourcesManifest(manifestValue);
   const bundle = envelope(bundleValue, "sources");
   if (bundle.digest !== manifest.digest) fail("$.bundle.digest", "does not match the Manifest digest");
   const bundleFiles = object(bundle.files, "$.bundle.files");
@@ -189,6 +193,7 @@ export function validateDiscovery(value) {
     const url = string(sources[key], `$.capabilities.sources.${key}`);
     try { new URL(url); } catch { fail(`$.capabilities.sources.${key}`, "must be an absolute URL"); }
   }
+  if (sources.mcp !== undefined) absoluteUrl(sources.mcp, "$.capabilities.sources.mcp");
   if (capabilities.systems) absoluteUrl(object(capabilities.systems, "$.capabilities.systems").document, "$.capabilities.systems.document");
   if (capabilities.changes) {
     const changes = object(capabilities.changes, "$.capabilities.changes");