@unfragile/mcp-server 0.3.2 → 0.5.0

package/README.md

@@ -59,12 +59,38 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ## Tools
 
+### Resolve (the headline call)
+
+| Tool | Description |
+|------|-------------|
+| `unfragile_resolve` | **Sprint 4.0 headline.** Resolve an agent intent into the single best AI artifact to invoke, with an invocation-ready snippet, an Ed25519-signed trust passport, and ranked alternatives. The outside calibration layer for agent tool selection. |
+
+Example:
+
+```typescript
+// From any MCP-compatible agent
+await mcpClient.callTool("unfragile_resolve", {
+  intent: "send email from agent",
+  context: { language: "typescript", deploymentTarget: "vercel" },
+});
+
+// Returns the single best match with:
+// - Invocation snippet ready to copy/paste
+// - Ed25519-signed trust passport (offline-verifiable)
+// - Top 3 alternatives with why_alternative
+// - matchConfidence score
+```
+
+Use `unfragile_resolve` when an agent has decided WHAT it wants to do and needs to choose WHICH artifact to call. Use `search` (below) when an agent needs to browse alternatives rather than commit to one.
+
+### Discovery and trust (human-readable)
+
 | Tool | Description |
 |------|-------------|
 | `search` | Find AI tools by intent. "best framework for building AI agents" |
 | `find_mcps` | Discover MCP servers by capability. "Postgres + Slack integration" |
 | `get_artifact` | Get full details + capabilities for a specific artifact |
-| `resolve_capability` | Resolve a `capability://...` URI to ranked trusted artifacts |
+| `resolve_capability` | Resolve a `capability://...` URI to ranked trusted artifacts (GET-based, formatted) |
 | `trust_passport` | Get machine-readable trust evidence: capability URIs, permissions, data access risk, failure modes |
 | `compare` | Compare two artifacts side-by-side |
 | `find_stack` | Assemble a complete harness stack for a use case |
@@ -72,6 +98,16 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `subscribe` | Watch for new artifacts matching a capability need |
 | `unsubscribe` | Cancel a monitor |
 
+### Capability Protocol v1 (raw JSON, machine-readable)
+
+| Tool | Description |
+|------|-------------|
+| `unfragile_validate` | Validate an `unfragile.yml` manifest against the Capability Protocol v1 schema. Returns errors, warnings, and the parsed manifest. |
+| `unfragile_passport` | Fetch the raw `trust_passport_v1` JSON for an artifact by slug. Suitable for programmatic policy checks. |
+| `unfragile_resolve_capability` | Resolve a `capability://` URI or natural-language intent into ranked artifacts as raw JSON. Optional inline passports for one-call decisioning. |
+
+Learn more about the protocol: <https://unfragile.ai/protocol>.
+
 ## Examples
 
 Once installed, ask your agent:

package/dist/index.js

@@ -7,16 +7,22 @@
 // the graph learns from every interaction.
 //
 // Tools:
-//   search         — Find AI tools by intent/query (with Match Proof)
-//   find_mcps      — Discover MCP servers by capability need
-//   get_artifact   — Get full details + capabilities for an artifact
-//   resolve_capability — Resolve capability:// URIs to trusted artifacts
-//   trust_passport — Get machine-readable trust passport for an artifact
-//   compare        — Compare two artifacts side-by-side
-//   find_stack     — Assemble a complete harness stack for a use case
-//   feedback       — Report success/failure to close the learning loop
-//   subscribe      — Set up persistent watch for new tools
-//   unsubscribe    — Cancel a persistent watch
+//   unfragile_resolve            — HEADLINE: Resolve intent → invocation-ready artifact + signed passport (POST /api/v1/resolve)
+//   search                       — Find AI tools by intent/query (with Match Proof)
+//   find_mcps                    — Discover MCP servers by capability need
+//   get_artifact                 — Get full details + capabilities for an artifact
+//   resolve_capability           — Resolve capability:// URIs to trusted artifacts (formatted, GET-based)
+//   trust_passport               — Get machine-readable trust passport for an artifact (formatted)
+//   compare                      — Compare two artifacts side-by-side
+//   find_stack                   — Assemble a complete harness stack for a use case
+//   feedback                     — Report success/failure to close the learning loop
+//   subscribe                    — Set up persistent watch for new tools
+//   unsubscribe                  — Cancel a persistent watch
+//
+// Protocol-native (raw JSON, Unfragile Capability Protocol v1):
+//   unfragile_validate           — Validate an unfragile.yml manifest
+//   unfragile_passport           — Raw trust passport JSON for an artifact
+//   unfragile_resolve_capability — Raw resolver JSON for a capability:// URI / intent (GET-based)
 // ─────────────────────────────────────────────────────────────
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -108,6 +114,42 @@ async function resolveAPI(capability, options = {}) {
         clearTimeout(timeout);
     }
 }
+// POST /api/v1/resolve — the headline DNS-for-agents call.
+// Takes a natural-language intent (or capability:// URI) and returns
+// invocation-ready snippets + signed passports + ranked alternatives.
+async function resolvePostAPI(intent, options = {}) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    if (API_KEY)
+        headers["X-API-Key"] = API_KEY;
+    const body = { intent };
+    if (options.context)
+        body.context = options.context;
+    if (options.type)
+        body.type = options.type;
+    if (options.limit)
+        body.limit = options.limit;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/resolve`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Unfragile resolve POST API error ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 // ─── Formatters ──────────────────────────────────────────────
 /** Extract a readable name from a URL when artifact.name is a raw URL */
 function cleanName(name, url) {
@@ -222,6 +264,58 @@ function formatPassport(data) {
     lines.push(`→ Artifact page: ${p.artifact.page_url}`);
     return lines.join("\n");
 }
+function formatResolvePost(data, intent) {
+    const lines = [];
+    lines.push(`# Resolved for intent: "${intent}"`);
+    lines.push(`Resolver: ${data.resolverVersion} | Generated: ${data.resolvedAt}${data.fromCache ? " (cached)" : ""}`);
+    if (data.resolved.length === 0) {
+        lines.push("\nNo trusted artifact resolved for this intent. This is a demand gap — the Unfragile graph has recorded it.");
+        return lines.join("\n");
+    }
+    for (let i = 0; i < data.resolved.length; i++) {
+        const r = data.resolved[i];
+        const signed = r.trust.signature ? " ✓ cryptographically signed" : "";
+        lines.push(`\n## ${i + 1}. ${r.artifact.name}${signed}`);
+        lines.push(`**Type:** ${r.artifact.type} | **Match confidence:** ${Math.round(r.matchConfidence * 100)}%`);
+        lines.push(`**URL:** ${r.artifact.url}`);
+        lines.push(`\n**Capability:** ${r.capability.name}`);
+        lines.push(`Intent fit: "${r.capability.intent}"`);
+        lines.push(`\n**Invocation (${r.invocation.language}):**`);
+        lines.push("```");
+        lines.push(r.invocation.snippet);
+        lines.push("```");
+        if (r.invocation.requires && r.invocation.requires.length > 0) {
+            lines.push(`Requires: ${r.invocation.requires.join(", ")}`);
+        }
+        if (r.trust.verified) {
+            lines.push(`\n**Trust:** Verified, Ed25519-signed.`);
+            if (r.trust.score !== undefined)
+                lines.push(`Trust score: ${r.trust.score}/100`);
+            if (r.trust.data_access_risk)
+                lines.push(`Data access risk: ${r.trust.data_access_risk}`);
+            if (r.trust.observed_outcomes) {
+                const o = r.trust.observed_outcomes;
+                lines.push(`Observed: ${o.matches} matches, ${Math.round(o.success_rate * 100)}% success`);
+            }
+            if (r.trust.signedBy && r.trust.signature) {
+                lines.push(`Signed by: ${r.trust.signedBy} (sig: ${r.trust.signature.slice(0, 16)}…)`);
+            }
+        }
+        else {
+            lines.push(`\n**Trust:** Unverified — no signed passport. Verify before production use.`);
+        }
+        if (r.alternatives.length > 0) {
+            lines.push(`\n**Alternatives:**`);
+            for (const alt of r.alternatives) {
+                lines.push(`- ${alt.name} (${alt.slug}) — ${alt.why_alternative}`);
+            }
+        }
+        if (r.lastVerified) {
+            lines.push(`\nLast verified: ${r.lastVerified}`);
+        }
+    }
+    return lines.join("\n");
+}
 function formatResolve(data) {
     const lines = [];
     lines.push(`# Resolve: ${data.capability}`);
@@ -257,7 +351,35 @@ function formatResolve(data) {
 // ─── MCP Server ──────────────────────────────────────────────
 const server = new McpServer({
     name: "unfragile",
-    version: "0.3.0",
+    version: "0.5.0",
+});
+// Tool 0: Resolve (HEADLINE — DNS for agents, Sprint 4.0)
+//
+// This is the call most agents should make most of the time when
+// they need to choose WHICH artifact to invoke for a task. Wraps
+// POST /api/v1/resolve, returns invocation-ready snippets +
+// Ed25519-signed trust passport + alternatives + match confidence.
+server.tool("unfragile_resolve", "RESOLVE an agent intent into the single best AI artifact to invoke, with an invocation-ready snippet, a cryptographically signed trust passport, and alternatives. This is Unfragile's headline call — the outside calibration layer for agent tool selection. Use this when an agent needs to choose WHICH tool/MCP/API/framework/model to invoke for a task it has decided to do. Returns the safest current option, not a list.", {
+    intent: z.string().min(2).max(500).describe("Natural-language intent (e.g., 'send email from agent', 'query Postgres read-only', 'transcribe an audio file'). Can also be a capability:// URI."),
+    context: z.record(z.unknown()).optional().describe("Free-form constraints — project size, language, deployment target, anything the resolver should factor in"),
+    type: z.enum(["agent", "api", "app", "benchmark", "cli", "dataset", "extension", "finetune", "framework", "mcp", "model", "platform", "product", "prompt", "repo", "skill", "template", "webapp", "workflow"]).optional().describe("Restrict the resolved artifact to a specific type"),
+    limit: z.number().min(1).max(10).default(1).describe("Number of resolutions to return (default 1 — use 1 unless you need backup options inline)"),
+    raw: z.boolean().default(false).describe("Return raw JSON for programmatic consumption (default false returns human-readable)"),
+}, async ({ intent, context, type, limit, raw }) => {
+    log("unfragile_resolve", intent);
+    try {
+        const data = await resolvePostAPI(intent, { context, type, limit });
+        const text = raw
+            ? JSON.stringify(data, null, 2)
+            : formatResolvePost(data, intent);
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error resolving intent: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
 });
 // Tool 1: General search
 server.tool("search", "Search the Unfragile match graph for AI tools, frameworks, APIs, MCP servers, agents, and more. Returns ranked results with capability matches and graph signals. Every query feeds the graph.", {
@@ -598,6 +720,111 @@ server.tool("subscribe", "Set up a persistent watch for new AI tools matching a
         };
     }
 });
+// ─── Protocol-native tools ──────────────────────────────────
+//
+// These three tools mirror the Unfragile Capability Protocol
+// endpoints 1:1 and return raw JSON. Use them when you want
+// machine-readable output rather than the formatted markdown
+// returned by `trust_passport` / `resolve_capability`.
+async function validateManifestAPI(body) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    if (API_KEY)
+        headers["X-API-Key"] = API_KEY;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/validate`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Validator returned non-JSON (${res.status}): ${text.slice(0, 300)}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// Tool: unfragile_validate
+server.tool("unfragile_validate", "Validate an unfragile.yml manifest against the Unfragile Capability Protocol v1. Returns the structured validation result with errors, warnings, and the parsed manifest. Use this before submitting an artifact or in CI pipelines. Accepts raw YAML text via `yaml_content`.", {
+    yaml_content: z
+        .string()
+        .min(10)
+        .max(200_000)
+        .describe("Raw contents of the unfragile.yml file"),
+}, async ({ yaml_content }) => {
+    log("unfragile_validate", `${yaml_content.length} bytes`);
+    try {
+        const data = await validateManifestAPI({ yaml: yaml_content });
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                { type: "text", text: `Error validating manifest: ${err instanceof Error ? err.message : String(err)}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: unfragile_passport — raw JSON trust passport
+server.tool("unfragile_passport", "Fetch the raw machine-readable trust passport for an artifact by slug (trust_passport_v1 schema). Returns JSON suitable for programmatic policy checks. Pair with `trust_passport` when you want a human-readable summary.", {
+    slug: z.string().min(1).max(200).describe("Artifact slug (e.g., 'cursor', 'langchain', 'postgres-mcp-server')"),
+}, async ({ slug }) => {
+    log("unfragile_passport", slug);
+    try {
+        const data = await passportAPI(slug);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                { type: "text", text: `Error fetching passport: ${err instanceof Error ? err.message : String(err)}` },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: unfragile_resolve_capability — raw JSON resolver
+server.tool("unfragile_resolve_capability", "Resolve a `capability://` URI or a natural-language capability into ranked artifacts, with trust signals and passport URLs. Returns raw JSON so an agent can make a programmatic selection. Pair with `resolve_capability` when you want a human-readable summary.", {
+    uri_or_intent: z
+        .string()
+        .min(2)
+        .max(500)
+        .describe("Capability URI like `capability://database.postgres.query.readonly`, or a natural-language capability description"),
+    limit: z.number().min(1).max(20).default(5).describe("Max resolutions"),
+    risk: z
+        .enum(["default", "production", "enterprise", "strict"])
+        .default("default")
+        .describe("Risk posture — stricter modes require stronger quality/status gates"),
+    passport: z
+        .boolean()
+        .default(false)
+        .describe("Inline the full trust passport for each resolution (larger response)"),
+}, async ({ uri_or_intent, limit, risk, passport }) => {
+    log("unfragile_resolve_capability", uri_or_intent);
+    try {
+        const data = await resolveAPI(uri_or_intent, { limit, risk, passport });
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                { type: "text", text: `Error resolving capability: ${err instanceof Error ? err.message : String(err)}` },
+            ],
+            isError: true,
+        };
+    }
+});
 // Tool 10: Unsubscribe — delete a monitor
 server.tool("unsubscribe", "Cancel a persistent watch (monitor). Use the monitor ID returned from subscribe.", {
     monitorId: z.string().min(1).describe("Monitor ID from subscribe (e.g., 'mon_...')"),

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@unfragile/mcp-server",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "mcpName": "io.github.Savirinc/unfragile",
-  "description": "Unfragile MCP Server — agent-native discovery, trust, and routing for AI artifacts.",
+  "description": "Unfragile MCP Server — agent-native discovery, trust, and routing for AI artifacts. Implements the Unfragile Capability Protocol v1.",
   "keywords": [
     "mcp",
     "ai",
@@ -12,7 +12,9 @@
     "routing",
     "capabilities",
     "unfragile",
-    "harness-engineering"
+    "harness-engineering",
+    "capability-protocol",
+    "unfragile.yml"
   ],
   "license": "MIT",
   "author": "Unfragile <hello@unfragile.ai>",