@unfragile/mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -59,6 +59,30 @@ 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 |
@@ -66,7 +90,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `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 |

package/dist/index.js

@@ -7,10 +7,11 @@
 // the graph learns from every interaction.
 //
 // Tools:
+//   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)
+//   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
@@ -21,7 +22,7 @@
 // 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
+//   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";
@@ -113,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) {
@@ -227,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}`);
@@ -262,7 +351,35 @@ function formatResolve(data) {
 // ─── MCP Server ──────────────────────────────────────────────
 const server = new McpServer({
     name: "unfragile",
-    version: "0.4.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.", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unfragile/mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "mcpName": "io.github.Savirinc/unfragile",
   "description": "Unfragile MCP Server — agent-native discovery, trust, and routing for AI artifacts. Implements the Unfragile Capability Protocol v1.",
   "keywords": [