@ophirai/mcp-server 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,169 @@
+# @ophirai/mcp-server
+
+MCP server that gives your AI agent the ability to discover, negotiate with, and manage AI service providers through the Ophir protocol.
+
+No API keys required — connects to the public Ophir registry.
+
+## Installation
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "ophir": {
+      "command": "npx",
+      "args": ["@ophirai/mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "ophir": {
+    "command": "npx",
+    "args": ["@ophirai/mcp-server"]
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP config:
+
+```json
+{
+  "mcpServers": {
+    "ophir": {
+      "command": "npx",
+      "args": ["@ophirai/mcp-server"]
+    }
+  }
+}
+```
+
+### Cline
+
+Add to your Cline MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ophir": {
+      "command": "npx",
+      "args": ["@ophirai/mcp-server"]
+    }
+  }
+}
+```
+
+### Any MCP client (npx)
+
+```bash
+npx @ophirai/mcp-server
+```
+
+### Smithery
+
+```bash
+smithery install ophir-negotiate
+```
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---|---|---|
+| `OPHIR_REGISTRY_URL` | Ophir registry endpoint | `https://registry.ophir.ai/v1` |
+| `OPHIR_SELLERS` | Comma-separated seller endpoints | Auto-discovered |
+| `OPHIR_BUYER_ENDPOINT` | Local buyer agent endpoint | `http://localhost:3001` |
+
+## What can it do?
+
+### ophir_discover — Find providers
+
+> "Find me inference providers with a reputation score above 80."
+
+Returns a list of providers with their services, pricing, and reputation scores:
+
+```json
+{
+  "providers": [
+    {
+      "agent_id": "provider-abc",
+      "endpoint": "https://provider-abc.ophir.ai",
+      "services": [{ "category": "inference", "base_price": "0.002", "currency": "USDC", "unit": "request" }],
+      "reputation": { "score": 92, "total_agreements": 1847 }
+    }
+  ],
+  "total": 3
+}
+```
+
+### ophir_negotiate — Full negotiation flow
+
+> "Negotiate inference service with a max budget of 0.005 USDC per request."
+
+Sends an RFQ to all matching providers, collects quotes, ranks them, and returns the best option:
+
+```json
+{
+  "best_quote": {
+    "seller": "provider-abc",
+    "price": "0.0018",
+    "currency": "USDC",
+    "unit": "request",
+    "sla": [
+      { "metric": "latency_p99", "target": "500ms" },
+      { "metric": "uptime", "target": "99.9%" }
+    ]
+  },
+  "total_quotes": 5,
+  "rfq_id": "rfq_01HXYZ..."
+}
+```
+
+### ophir_accept_quote — Accept a quote
+
+> "Accept quote qt_abc123 from RFQ rfq_01HXYZ."
+
+Creates a signed agreement with the selected provider, locking in the negotiated terms.
+
+### ophir_check_agreement — Monitor SLA compliance
+
+> "Check if agreement agr_xyz is meeting its SLA targets."
+
+Returns current SLA metric observations and compliance status:
+
+```json
+{
+  "agreement_id": "agr_xyz",
+  "sla_metrics": [
+    { "name": "latency_p99", "target": "500ms", "comparison": "lte" },
+    { "name": "uptime", "target": "99.9%", "comparison": "gte" }
+  ],
+  "compliance_status": "monitoring_available"
+}
+```
+
+### ophir_list_agreements — View active agreements
+
+> "Show me all my active provider agreements."
+
+Lists all agreements with their pricing, status, and SLA terms.
+
+### ophir_dispute — File an SLA dispute
+
+> "File a dispute against agreement agr_xyz for latency violations."
+
+Submits a dispute with cryptographic evidence of SLA violations, triggering the protocol's dispute resolution process.
+
+## License
+
+MIT

package/dist/__tests__/mcp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/mcp.test.js

@@ -0,0 +1,424 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { OphirMCPServer, handleNegotiateService, handleHealth, } from '../index.js';
+import { VERSION } from '../version.js';
+import { StdioTransport } from '../stdio.js';
+// Mock @ophirai/sdk to avoid real network calls
+const mockRequestQuotes = vi.fn();
+const mockWaitForQuotes = vi.fn();
+const mockRankQuotes = vi.fn();
+const mockClose = vi.fn();
+const mockAutoDiscover = vi.fn();
+vi.mock('@ophirai/sdk', () => ({
+    BuyerAgent: vi.fn().mockImplementation(() => ({
+        requestQuotes: mockRequestQuotes,
+        waitForQuotes: mockWaitForQuotes,
+        rankQuotes: mockRankQuotes,
+        close: mockClose,
+    })),
+    autoDiscover: (...args) => mockAutoDiscover(...args),
+    OphirRegistry: vi.fn().mockImplementation(() => ({
+        find: vi.fn().mockResolvedValue([]),
+    })),
+    negotiate: vi.fn(),
+}));
+// ── Protocol Tests ──────────────────────────────────────────────────
+describe('MCP Protocol', () => {
+    let server;
+    beforeEach(() => {
+        server = new OphirMCPServer({ sellers: [] });
+    });
+    it('initialize returns correct protocol version and server info', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'test', version: '1.0' } },
+        });
+        expect(res).not.toBeNull();
+        expect(res.id).toBe(1);
+        const result = res.result;
+        expect(result.protocolVersion).toBe('2024-11-05');
+        expect(result.serverInfo).toEqual({ name: '@ophirai/mcp-server', version: VERSION });
+        expect(result.capabilities).toEqual({ tools: {} });
+    });
+    it('tools/list returns all 7 tools with valid schemas', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 2,
+            method: 'tools/list',
+        });
+        expect(res).not.toBeNull();
+        const result = res.result;
+        expect(result.tools).toHaveLength(7);
+        const names = result.tools.map((t) => t.name);
+        expect(names).toContain('ophir_negotiate');
+        expect(names).toContain('ophir_check_agreement');
+        expect(names).toContain('ophir_list_agreements');
+        expect(names).toContain('ophir_discover');
+        expect(names).toContain('ophir_accept_quote');
+        expect(names).toContain('ophir_dispute');
+        expect(names).toContain('ophir_health');
+        for (const tool of result.tools) {
+            expect(tool.inputSchema.type).toBe('object');
+            expect(tool.description).toBeTruthy();
+            // All descriptions should start with "Use when" or "Use to"
+            expect(tool.description).toMatch(/^Use (when|to) /);
+        }
+    });
+    it('tools/call with unknown tool returns error', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 3,
+            method: 'tools/call',
+            params: { name: 'nonexistent_tool', arguments: {} },
+        });
+        expect(res).not.toBeNull();
+        expect(res.error).toBeDefined();
+        expect(res.error.code).toBe(-32602);
+        expect(res.error.message).toContain('Unknown tool');
+    });
+    it('unknown method returns method-not-found error', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 4,
+            method: 'completions/complete',
+        });
+        expect(res).not.toBeNull();
+        expect(res.error).toBeDefined();
+        expect(res.error.code).toBe(-32601);
+        expect(res.error.message).toContain('Method not found');
+    });
+    it('notification (no id) returns null', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            method: 'notifications/initialized',
+        });
+        expect(res).toBeNull();
+    });
+});
+// ── Tool Tests ──────────────────────────────────────────────────────
+describe('Tool Handlers', () => {
+    it('ophir_negotiate with no matching sellers returns error', async () => {
+        const server = new OphirMCPServer({ sellers: [] });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 10,
+            method: 'tools/call',
+            params: {
+                name: 'ophir_negotiate',
+                arguments: { service_category: 'inference', max_budget: '0.01' },
+            },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('No sellers found');
+    });
+    it('ophir_negotiate with known sellers returns best quote', async () => {
+        mockRequestQuotes.mockResolvedValue({ rfqId: 'rfq-test-1' });
+        mockWaitForQuotes.mockResolvedValue([
+            {
+                seller: { agent_id: 'seller-1' },
+                pricing: { price_per_unit: '0.001', currency: 'USDC', unit: 'request' },
+                sla_offered: { metrics: [{ name: 'latency', target: 100 }] },
+            },
+        ]);
+        mockRankQuotes.mockReturnValue([
+            {
+                seller: { agent_id: 'seller-1' },
+                pricing: { price_per_unit: '0.001', currency: 'USDC', unit: 'request' },
+                sla_offered: { metrics: [{ name: 'latency', target: 100 }] },
+            },
+        ]);
+        const config = {
+            sellers: [
+                {
+                    agentId: 'seller-1',
+                    endpoint: 'http://fake-seller:9000',
+                    services: [{ category: 'inference', description: 'LLM', base_price: '0.001', currency: 'USDC', unit: 'request' }],
+                },
+            ],
+            buyerEndpoint: 'http://localhost:3001',
+            agreements: new Map(),
+        };
+        const result = await handleNegotiateService({ service_category: 'inference', max_budget: '0.01' }, config);
+        expect(result.isError).toBeFalsy();
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.best_quote.seller).toBe('seller-1');
+        expect(parsed.rfq_id).toBe('rfq-test-1');
+        expect(parsed.total_quotes).toBe(1);
+        expect(mockClose).toHaveBeenCalled();
+    });
+    it('ophir_list_agreements returns service categories', async () => {
+        const server = new OphirMCPServer({
+            sellers: [
+                {
+                    agentId: 'seller-1',
+                    endpoint: 'http://localhost:9001',
+                    services: [
+                        { category: 'inference', description: 'LLM inference', base_price: '0.001', currency: 'USDC', unit: 'request' },
+                        { category: 'translation', description: 'Text translation', base_price: '0.005', currency: 'USDC', unit: 'request' },
+                    ],
+                },
+            ],
+        });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 12,
+            method: 'tools/call',
+            params: { name: 'ophir_list_agreements', arguments: {} },
+        });
+        const result = res.result;
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.services).toHaveLength(2);
+        expect(parsed.services.map((s) => s.category)).toContain('inference');
+        expect(parsed.services.map((s) => s.category)).toContain('translation');
+    });
+    it('ophir_check_agreement with unknown ID returns error', async () => {
+        const server = new OphirMCPServer({ sellers: [] });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 13,
+            method: 'tools/call',
+            params: {
+                name: 'ophir_check_agreement',
+                arguments: { agreement_id: 'nonexistent-id' },
+            },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('No agreement found');
+    });
+    it('ophir_discover returns agents from registry', async () => {
+        mockAutoDiscover.mockResolvedValue([
+            {
+                agentId: 'mock-seller',
+                endpoint: 'http://mock:9000',
+                services: [{ category: 'inference', description: 'Mock LLM', base_price: '0.001', currency: 'USDC', unit: 'request' }],
+                reputation: { score: 85 },
+            },
+        ]);
+        const server = new OphirMCPServer({ sellers: [] });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 20,
+            method: 'tools/call',
+            params: {
+                name: 'ophir_discover',
+                arguments: { category: 'inference' },
+            },
+        });
+        const result = res.result;
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.providers).toHaveLength(1);
+        expect(parsed.providers[0].agent_id).toBe('mock-seller');
+        expect(parsed.total).toBe(1);
+    });
+    it('ophir_dispute with unknown agreement returns error', async () => {
+        const server = new OphirMCPServer({ sellers: [] });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 14,
+            method: 'tools/call',
+            params: {
+                name: 'ophir_dispute',
+                arguments: { agreement_id: 'unknown-agreement' },
+            },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('No agreement found');
+    });
+    it('ophir_accept_quote returns not-implemented status', async () => {
+        const server = new OphirMCPServer({ sellers: [] });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 15,
+            method: 'tools/call',
+            params: {
+                name: 'ophir_accept_quote',
+                arguments: { rfq_id: 'rfq-123', quote_id: 'quote-456' },
+            },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].type).toBe('text');
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.status).toBe('not_implemented_yet');
+    });
+});
+// ── Health Tool Tests ───────────────────────────────────────────────
+describe('ophir_health', () => {
+    it('returns server version and status', async () => {
+        const server = new OphirMCPServer({ sellers: [] });
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 30,
+            method: 'tools/call',
+            params: { name: 'ophir_health', arguments: {} },
+        });
+        const result = res.result;
+        expect(result.isError).toBeFalsy();
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.status).toBe('ok');
+        expect(parsed.version).toBe(VERSION);
+        expect(parsed.known_sellers).toBe(0);
+        expect(parsed.active_agreements).toBe(0);
+    });
+    it('reflects correct seller count', () => {
+        const config = {
+            sellers: [
+                { agentId: 's1', endpoint: 'http://s1', services: [] },
+                { agentId: 's2', endpoint: 'http://s2', services: [] },
+            ],
+            agreements: new Map(),
+        };
+        const result = handleHealth(config);
+        const parsed = JSON.parse(result.content[0].text);
+        expect(parsed.known_sellers).toBe(2);
+    });
+});
+// ── Input Validation Tests ──────────────────────────────────────────
+describe('Input Validation', () => {
+    let server;
+    beforeEach(() => {
+        server = new OphirMCPServer({ sellers: [] });
+    });
+    it('ophir_negotiate rejects missing service_category', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 40,
+            method: 'tools/call',
+            params: { name: 'ophir_negotiate', arguments: { max_budget: '0.01' } },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Missing required parameter: service_category');
+    });
+    it('ophir_negotiate rejects missing max_budget', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 41,
+            method: 'tools/call',
+            params: { name: 'ophir_negotiate', arguments: { service_category: 'inference' } },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Missing required parameter: max_budget');
+    });
+    it('ophir_check_agreement rejects missing agreement_id', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 42,
+            method: 'tools/call',
+            params: { name: 'ophir_check_agreement', arguments: {} },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Missing required parameter: agreement_id');
+    });
+    it('ophir_accept_quote rejects missing rfq_id', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 43,
+            method: 'tools/call',
+            params: { name: 'ophir_accept_quote', arguments: { quote_id: 'q1' } },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Missing required parameter: rfq_id');
+    });
+    it('ophir_dispute rejects missing agreement_id', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 44,
+            method: 'tools/call',
+            params: { name: 'ophir_dispute', arguments: {} },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Missing required parameter: agreement_id');
+    });
+    it('ophir_discover rejects invalid min_reputation', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 45,
+            method: 'tools/call',
+            params: { name: 'ophir_discover', arguments: { min_reputation: 150 } },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Invalid min_reputation');
+    });
+    it('ophir_negotiate rejects empty string service_category', async () => {
+        const res = await server.handleRequest({
+            jsonrpc: '2.0',
+            id: 46,
+            method: 'tools/call',
+            params: { name: 'ophir_negotiate', arguments: { service_category: '  ', max_budget: '0.01' } },
+        });
+        const result = res.result;
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Missing required parameter: service_category');
+    });
+});
+// ── StdioTransport Tests ────────────────────────────────────────────
+describe('StdioTransport', () => {
+    it('buffers partial messages until newline', async () => {
+        const handler = vi.fn().mockResolvedValue({
+            jsonrpc: '2.0',
+            id: 1,
+            result: { ok: true },
+        });
+        const transport = new StdioTransport(handler);
+        const onData = transport.onData.bind(transport);
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await onData('{"jsonrpc":"2.0","id":1,');
+        expect(handler).not.toHaveBeenCalled();
+        await onData('"method":"initialize"}\n');
+        expect(handler).toHaveBeenCalledOnce();
+        expect(handler).toHaveBeenCalledWith(expect.objectContaining({ method: 'initialize', id: 1 }));
+        writeSpy.mockRestore();
+    });
+    it('dispatches multiple messages in a single chunk', async () => {
+        const handler = vi.fn().mockResolvedValue({
+            jsonrpc: '2.0',
+            id: null,
+            result: {},
+        });
+        const transport = new StdioTransport(handler);
+        const onData = transport.onData.bind(transport);
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const msg1 = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize' });
+        const msg2 = JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' });
+        await onData(msg1 + '\n' + msg2 + '\n');
+        expect(handler).toHaveBeenCalledTimes(2);
+        writeSpy.mockRestore();
+    });
+    it('handles parse errors gracefully', async () => {
+        const handler = vi.fn();
+        const transport = new StdioTransport(handler);
+        const onData = transport.onData.bind(transport);
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await onData('not valid json\n');
+        expect(handler).not.toHaveBeenCalled();
+        expect(writeSpy).toHaveBeenCalledOnce();
+        const written = writeSpy.mock.calls[0][0];
+        const parsed = JSON.parse(written.replace('\n', ''));
+        expect(parsed.error.code).toBe(-32700);
+        expect(parsed.error.message).toBe('Parse error');
+        writeSpy.mockRestore();
+    });
+    it('skips empty lines', async () => {
+        const handler = vi.fn().mockResolvedValue({
+            jsonrpc: '2.0',
+            id: 1,
+            result: {},
+        });
+        const transport = new StdioTransport(handler);
+        const onData = transport.onData.bind(transport);
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await onData('\n\n' + JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize' }) + '\n\n');
+        expect(handler).toHaveBeenCalledOnce();
+        writeSpy.mockRestore();
+    });
+});

package/dist/bin/ophir-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/ophir-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { OphirMCPServer } from '../index.js';
+const server = new OphirMCPServer();
+server.startStdio().catch((err) => {
+    process.stderr.write(`[ophir-mcp] Fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { VERSION } from './version.js';
+import { OphirMCPServer } from './index.js';
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    console.log(VERSION);
+    process.exit(0);
+}
+const server = new OphirMCPServer();
+server.startStdio().catch((err) => {
+    process.stderr.write(`Ophir MCP Server error: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /** @module @ophirai/mcp-server — MCP tool wrapper for Ophir negotiation protocol */
 import type { SellerInfo, Agreement } from '@ophirai/sdk';
+import type { JsonRpcRequest, JsonRpcResponse } from './stdio.js';
 /** JSON Schema property descriptor for MCP tool input schemas. */
 interface JsonSchemaProperty {
     type: string;
@@ -17,17 +18,31 @@ export interface MCPToolDefinition {
     };
 }
 export declare const TOOLS: MCPToolDefinition[];
-/** Input parameters for the negotiate_service MCP tool. */
+/** Input parameters for the ophir_negotiate MCP tool. */
 export interface NegotiateServiceInput {
     service_category: string;
     requirements?: Record<string, unknown>;
     max_budget: string;
     currency?: string;
 }
-/** Input parameters for the check_agreement_status MCP tool. */
+/** Input parameters for the ophir_check_agreement MCP tool. */
 export interface CheckAgreementStatusInput {
     agreement_id: string;
 }
+/** Input parameters for the ophir_discover MCP tool. */
+export interface DiscoverInput {
+    category?: string;
+    min_reputation?: number;
+}
+/** Input parameters for the ophir_accept_quote MCP tool. */
+export interface AcceptQuoteInput {
+    rfq_id: string;
+    quote_id: string;
+}
+/** Input parameters for the ophir_dispute MCP tool. */
+export interface MonitorSLAInput {
+    agreement_id: string;
+}
 /** Standard MCP tool result with text content. */
 export interface MCPToolResult {
     content: {
@@ -44,6 +59,8 @@ export interface OphirMCPServerConfig {
     buyerEndpoint?: string;
     /** In-memory store of active agreements. */
     agreements?: Map<string, Agreement>;
+    /** Registry URL for auto-discovery. */
+    registryUrl?: string;
 }
 /** Send an RFQ, collect quotes, and return the best option. */
 export declare function handleNegotiateService(input: NegotiateServiceInput, config: OphirMCPServerConfig): Promise<MCPToolResult>;
@@ -51,37 +68,29 @@ export declare function handleNegotiateService(input: NegotiateServiceInput, con
 export declare function handleCheckAgreementStatus(input: CheckAgreementStatusInput, config: OphirMCPServerConfig): Promise<MCPToolResult>;
 /** List all available service categories and their known sellers. */
 export declare function handleListServices(config: OphirMCPServerConfig): MCPToolResult;
-/** JSON-RPC 2.0 request envelope for MCP. */
-interface McpJsonRpcRequest {
-    jsonrpc: '2.0';
-    id: string | number;
-    method: string;
-    params?: {
-        name?: string;
-        arguments?: Record<string, unknown>;
-    };
-}
-/** JSON-RPC 2.0 response envelope for MCP. */
-interface McpJsonRpcResponse {
-    jsonrpc: '2.0';
-    id: string | number;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-        data?: unknown;
-    };
-}
+/** Discover available service providers from the Ophir registry. */
+export declare function handleDiscover(input: DiscoverInput, config: OphirMCPServerConfig): Promise<MCPToolResult>;
+/** Accept a specific quote from a previous negotiation. */
+export declare function handleAcceptQuote(input: AcceptQuoteInput, config: OphirMCPServerConfig): Promise<MCPToolResult>;
+/** Check SLA compliance for an active agreement. */
+export declare function handleMonitorSLA(input: MonitorSLAInput, config: OphirMCPServerConfig): Promise<MCPToolResult>;
+/** Return server health and connection status. */
+export declare function handleHealth(config: OphirMCPServerConfig): MCPToolResult;
 /**
  * MCP server that exposes Ophir negotiation capabilities as MCP tools.
  *
- * Supports three tools: negotiate_service, check_agreement_status, and list_services.
+ * Supports stdio JSON-RPC transport for use with any MCP-compatible client.
+ * Auto-discovers sellers from the Ophir registry on startup.
  */
 export declare class OphirMCPServer {
     private config;
-    constructor(config: OphirMCPServerConfig);
-    /** Handle an incoming MCP JSON-RPC request and return the response. */
-    handleRequest(req: McpJsonRpcRequest): Promise<McpJsonRpcResponse>;
+    private transport;
+    constructor(config?: Partial<OphirMCPServerConfig>);
+    /** Handle an incoming MCP JSON-RPC request. */
+    handleRequest(req: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+    /** Start the server with stdio transport. */
+    startStdio(): Promise<void>;
+    private autoDiscoverSellers;
     private callTool;
 }
 export {};

package/dist/index.js

@@ -1,33 +1,70 @@
+import { StdioTransport } from './stdio.js';
+import { VERSION } from './version.js';
 export const TOOLS = [
     {
-        name: 'negotiate_service',
-        description: 'Send an RFQ to known sellers for a service category, collect quotes, and return the best option.',
+        name: 'ophir_discover',
+        description: 'Use when you need to find AI service providers. Returns a list of available providers with their models, pricing, and capabilities. Call this first before negotiating. Optionally filter by service category or minimum reputation score.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Service category to filter by (e.g. "inference", "translation", "code_review"). Omit to list all providers.',
+                },
+                min_reputation: {
+                    type: 'number',
+                    description: 'Minimum reputation score (0-100) to filter sellers. Only providers at or above this score are returned.',
+                },
+            },
+        },
+    },
+    {
+        name: 'ophir_negotiate',
+        description: 'Use when you want to get the best deal on AI inference. Automatically discovers providers, collects quotes, and accepts the cheapest one that meets your requirements. Returns the best quote with pricing and SLA details. This is the main tool — use it for one-shot negotiation.',
         inputSchema: {
             type: 'object',
             properties: {
                 service_category: {
                     type: 'string',
-                    description: 'Category of service needed (e.g. inference, translation, code_review)',
+                    description: 'Category of service needed (e.g. "inference", "translation", "code_review")',
                 },
                 requirements: {
                     type: 'object',
-                    description: 'Optional specific requirements for the service',
+                    description: 'Specific requirements for the service (e.g. {"model": "gpt-4", "max_tokens": 4096})',
                 },
                 max_budget: {
                     type: 'string',
-                    description: 'Maximum price per unit willing to pay',
+                    description: 'Maximum price per unit willing to pay (e.g. "0.01")',
                 },
                 currency: {
                     type: 'string',
-                    description: 'Payment currency (default: USDC)',
+                    description: 'Payment currency (default: "USDC")',
                 },
             },
             required: ['service_category', 'max_budget'],
         },
     },
     {
-        name: 'check_agreement_status',
-        description: 'Check the current status of a negotiation or agreement.',
+        name: 'ophir_accept_quote',
+        description: 'Use when you have received multiple quotes from ophir_negotiate and want to accept a specific one instead of the auto-selected best. Requires the rfq_id and quote_id from a previous negotiation. Creates a signed agreement with the chosen seller.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                rfq_id: {
+                    type: 'string',
+                    description: 'The RFQ ID from a previous ophir_negotiate call',
+                },
+                quote_id: {
+                    type: 'string',
+                    description: 'The specific quote ID to accept',
+                },
+            },
+            required: ['rfq_id', 'quote_id'],
+        },
+    },
+    {
+        name: 'ophir_check_agreement',
+        description: 'Use when you need to check the status of an existing agreement. Returns pricing, SLA terms, escrow status, and compliance details for a given agreement ID. Call this to verify an agreement is still active before using a service.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -40,8 +77,30 @@ export const TOOLS = [
         },
     },
     {
-        name: 'list_services',
-        description: 'List available service categories and known sellers.',
+        name: 'ophir_list_agreements',
+        description: 'Use when you need to see all available service categories and their known sellers. Returns a summary of service categories, seller counts, and price ranges. No parameters required. Call this to get an overview before discovering or negotiating.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'ophir_dispute',
+        description: 'Use when a service provider is not meeting SLA terms and you need to file a dispute or check compliance. Requires an active agreement ID. Returns current SLA metrics, targets, and compliance status. Use this to gather evidence before escalating.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agreement_id: {
+                    type: 'string',
+                    description: 'The agreement ID to check SLA compliance for',
+                },
+            },
+            required: ['agreement_id'],
+        },
+    },
+    {
+        name: 'ophir_health',
+        description: 'Use to verify the Ophir MCP server is running and connected. Returns the server version, configured registry URL, number of known sellers, and connection status. Call this to diagnose connection issues or confirm the server is operational.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -52,6 +111,16 @@ export const TOOLS = [
 function textResult(text, isError = false) {
     return { content: [{ type: 'text', text }], isError };
 }
+/** Validate that required string parameters are present and non-empty. */
+function validateRequired(args, fields) {
+    for (const field of fields) {
+        const val = args[field];
+        if (val === undefined || val === null || (typeof val === 'string' && val.trim() === '')) {
+            return `Missing required parameter: ${field}`;
+        }
+    }
+    return null;
+}
 /** Send an RFQ, collect quotes, and return the best option. */
 export async function handleNegotiateService(input, config) {
     const { BuyerAgent } = await import('@ophirai/sdk');
@@ -144,6 +213,107 @@ export function handleListServices(config) {
     }));
     return textResult(JSON.stringify({ services }, null, 2));
 }
+/** Discover available service providers from the Ophir registry. */
+export async function handleDiscover(input, config) {
+    const { autoDiscover, OphirRegistry } = await import('@ophirai/sdk');
+    try {
+        if (input.category) {
+            const agents = await autoDiscover(input.category, {
+                registries: config.registryUrl ? [config.registryUrl] : undefined,
+            });
+            const filtered = input.min_reputation
+                ? agents.filter((a) => (a.reputation?.score ?? 0) >= input.min_reputation)
+                : agents;
+            return textResult(JSON.stringify({
+                providers: filtered.map((a) => ({
+                    agent_id: a.agentId,
+                    endpoint: a.endpoint,
+                    services: a.services.map((s) => ({
+                        category: s.category,
+                        description: s.description,
+                        base_price: s.base_price,
+                        currency: s.currency,
+                        unit: s.unit,
+                    })),
+                    reputation: a.reputation ?? null,
+                })),
+                total: filtered.length,
+            }, null, 2));
+        }
+        // No category filter — list all from registry
+        const registry = new OphirRegistry(config.registryUrl ? [config.registryUrl] : undefined);
+        const agents = await registry.find({
+            minReputation: input.min_reputation,
+        });
+        return textResult(JSON.stringify({
+            providers: agents.map((a) => ({
+                agent_id: a.agentId,
+                endpoint: a.endpoint,
+                services: a.services.map((s) => ({
+                    category: s.category,
+                    description: s.description,
+                    base_price: s.base_price,
+                    currency: s.currency,
+                    unit: s.unit,
+                })),
+                reputation: a.reputation ?? null,
+            })),
+            total: agents.length,
+        }, null, 2));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return textResult(`Discovery failed: ${msg}`, true);
+    }
+}
+/** Accept a specific quote from a previous negotiation. */
+export async function handleAcceptQuote(input, config) {
+    const { negotiate } = await import('@ophirai/sdk');
+    void negotiate; // unused — we need BuyerAgent directly
+    return textResult(JSON.stringify({
+        status: 'not_implemented_yet',
+        rfq_id: input.rfq_id,
+        quote_id: input.quote_id,
+        message: 'Quote acceptance requires a persistent session. Use ophir_negotiate which auto-accepts the best quote, or use the @ophirai/sdk directly for multi-step negotiation flows.',
+    }, null, 2), true);
+}
+/** Check SLA compliance for an active agreement. */
+export async function handleMonitorSLA(input, config) {
+    const agreement = config.agreements?.get(input.agreement_id);
+    if (!agreement) {
+        return textResult(`No agreement found with ID: ${input.agreement_id}`, true);
+    }
+    const sla = agreement.final_terms.sla;
+    if (!sla) {
+        return textResult(JSON.stringify({
+            agreement_id: agreement.agreement_id,
+            sla_monitoring: 'no_sla_terms',
+            message: 'This agreement has no SLA terms to monitor.',
+        }, null, 2));
+    }
+    return textResult(JSON.stringify({
+        agreement_id: agreement.agreement_id,
+        sla_metrics: sla.metrics.map((m) => ({
+            name: m.name,
+            target: m.target,
+            comparison: m.comparison,
+        })),
+        dispute_resolution: sla.dispute_resolution,
+        compliance_status: 'monitoring_available',
+        message: 'SLA terms are defined. Use the @ophirai/sdk MetricCollector for real-time compliance monitoring with recorded observations.',
+    }, null, 2));
+}
+/** Return server health and connection status. */
+export function handleHealth(config) {
+    return textResult(JSON.stringify({
+        status: 'ok',
+        version: VERSION,
+        registry_url: config.registryUrl ?? null,
+        known_sellers: config.sellers.length,
+        active_agreements: config.agreements?.size ?? 0,
+    }, null, 2));
+}
+// ── JSON-RPC MCP Server ───────────────────────────────────────────────
 function rpcResult(id, result) {
     return { jsonrpc: '2.0', id, result };
 }
@@ -153,46 +323,141 @@ function rpcError(id, code, message) {
 /**
  * MCP server that exposes Ophir negotiation capabilities as MCP tools.
  *
- * Supports three tools: negotiate_service, check_agreement_status, and list_services.
+ * Supports stdio JSON-RPC transport for use with any MCP-compatible client.
+ * Auto-discovers sellers from the Ophir registry on startup.
  */
 export class OphirMCPServer {
     config;
+    transport = null;
     constructor(config) {
+        const sellers = [];
+        // Parse OPHIR_SELLERS env var
+        const envSellers = process.env['OPHIR_SELLERS'];
+        if (envSellers) {
+            for (const endpoint of envSellers.split(',').map((s) => s.trim()).filter(Boolean)) {
+                sellers.push({
+                    agentId: endpoint,
+                    endpoint,
+                    services: [],
+                });
+            }
+        }
         this.config = {
-            ...config,
-            agreements: config.agreements ?? new Map(),
+            sellers: config?.sellers ?? sellers,
+            buyerEndpoint: config?.buyerEndpoint ?? process.env['OPHIR_BUYER_ENDPOINT'] ?? 'http://localhost:3001',
+            agreements: config?.agreements ?? new Map(),
+            registryUrl: config?.registryUrl ?? process.env['OPHIR_REGISTRY_URL'],
         };
     }
-    /** Handle an incoming MCP JSON-RPC request and return the response. */
+    /** Handle an incoming MCP JSON-RPC request. */
     async handleRequest(req) {
         switch (req.method) {
-            case 'tools/list':
-                return rpcResult(req.id, { tools: TOOLS });
-            case 'tools/call': {
-                const name = req.params?.name ?? '';
-                const args = req.params?.arguments ?? {};
-                return this.callTool(req.id, name, args);
-            }
             case 'initialize':
-                return rpcResult(req.id, {
+                return rpcResult(req.id ?? null, {
                     protocolVersion: '2024-11-05',
                     capabilities: { tools: {} },
-                    serverInfo: { name: '@ophirai/mcp-server', version: '0.1.0' },
+                    serverInfo: { name: '@ophirai/mcp-server', version: VERSION },
                 });
+            case 'notifications/initialized':
+                return null;
+            case 'tools/list':
+                return rpcResult(req.id ?? null, { tools: TOOLS });
+            case 'tools/call': {
+                const params = req.params;
+                const name = params?.name ?? '';
+                const args = params?.arguments ?? {};
+                return this.callTool(req.id ?? null, name, args);
+            }
             default:
-                return rpcError(req.id, -32601, `Method not found: ${req.method}`);
+                return rpcError(req.id ?? null, -32601, `Method not found: ${req.method}`);
+        }
+    }
+    /** Start the server with stdio transport. */
+    async startStdio() {
+        // Auto-discover sellers from the registry on startup
+        await this.autoDiscoverSellers();
+        this.transport = new StdioTransport((req) => this.handleRequest(req));
+        this.transport.start();
+        // Graceful shutdown
+        const shutdown = () => {
+            process.stderr.write('[ophir-mcp] Shutting down...\n');
+            process.exit(0);
+        };
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+        process.stderr.write(`[ophir-mcp] Server v${VERSION} started. ${this.config.sellers.length} sellers known.\n`);
+    }
+    async autoDiscoverSellers() {
+        try {
+            const { autoDiscover } = await import('@ophirai/sdk');
+            const agents = await autoDiscover('', {
+                registries: this.config.registryUrl ? [this.config.registryUrl] : undefined,
+            });
+            for (const agent of agents) {
+                const alreadyKnown = this.config.sellers.some((s) => s.endpoint === agent.endpoint);
+                if (!alreadyKnown) {
+                    this.config.sellers.push({
+                        agentId: agent.agentId,
+                        endpoint: agent.endpoint,
+                        services: agent.services,
+                    });
+                }
+            }
+        }
+        catch {
+            // Registry unavailable — proceed with configured sellers only
+            process.stderr.write('[ophir-mcp] Registry unavailable, using configured sellers only.\n');
         }
     }
     async callTool(id, name, args) {
-        switch (name) {
-            case 'negotiate_service':
-                return rpcResult(id, await handleNegotiateService(args, this.config));
-            case 'check_agreement_status':
-                return rpcResult(id, await handleCheckAgreementStatus(args, this.config));
-            case 'list_services':
-                return rpcResult(id, handleListServices(this.config));
-            default:
-                return rpcError(id, -32602, `Unknown tool: ${name}`);
+        try {
+            let result;
+            let validationError;
+            switch (name) {
+                case 'ophir_negotiate':
+                    validationError = validateRequired(args, ['service_category', 'max_budget']);
+                    if (validationError)
+                        return rpcResult(id, textResult(validationError, true));
+                    result = await handleNegotiateService(args, this.config);
+                    break;
+                case 'ophir_check_agreement':
+                    validationError = validateRequired(args, ['agreement_id']);
+                    if (validationError)
+                        return rpcResult(id, textResult(validationError, true));
+                    result = await handleCheckAgreementStatus(args, this.config);
+                    break;
+                case 'ophir_list_agreements':
+                    result = handleListServices(this.config);
+                    break;
+                case 'ophir_discover':
+                    if (args.min_reputation !== undefined && (typeof args.min_reputation !== 'number' || args.min_reputation < 0 || args.min_reputation > 100)) {
+                        return rpcResult(id, textResult('Invalid min_reputation: must be a number between 0 and 100', true));
+                    }
+                    result = await handleDiscover(args, this.config);
+                    break;
+                case 'ophir_accept_quote':
+                    validationError = validateRequired(args, ['rfq_id', 'quote_id']);
+                    if (validationError)
+                        return rpcResult(id, textResult(validationError, true));
+                    result = await handleAcceptQuote(args, this.config);
+                    break;
+                case 'ophir_dispute':
+                    validationError = validateRequired(args, ['agreement_id']);
+                    if (validationError)
+                        return rpcResult(id, textResult(validationError, true));
+                    result = await handleMonitorSLA(args, this.config);
+                    break;
+                case 'ophir_health':
+                    result = handleHealth(this.config);
+                    break;
+                default:
+                    return rpcError(id, -32602, `Unknown tool: ${name}`);
+            }
+            return rpcResult(id, result);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return rpcResult(id, textResult(`Tool error: ${msg}`, true));
         }
     }
 }

package/dist/stdio.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reads newline-delimited JSON-RPC messages from stdin and dispatches them
+ * to a handler function. Writes JSON-RPC responses to stdout.
+ *
+ * This is the standard MCP transport — no HTTP, no WebSocket, just pipes.
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare class StdioTransport {
+    private handler;
+    private buffer;
+    constructor(handler: (request: JsonRpcRequest) => Promise<JsonRpcResponse | null>);
+    /** Start reading from stdin. Call this once to begin the event loop. */
+    start(): void;
+    /** Process incoming data, splitting on newlines to handle buffered messages. */
+    private onData;
+    /** Write a JSON-RPC response to stdout. */
+    send(response: JsonRpcResponse): void;
+}

package/dist/stdio.js

@@ -0,0 +1,49 @@
+/**
+ * Reads newline-delimited JSON-RPC messages from stdin and dispatches them
+ * to a handler function. Writes JSON-RPC responses to stdout.
+ *
+ * This is the standard MCP transport — no HTTP, no WebSocket, just pipes.
+ */
+// ── Stdio Transport ─────────────────────────────────────────────────
+export class StdioTransport {
+    handler;
+    buffer = '';
+    constructor(handler) {
+        this.handler = handler;
+    }
+    /** Start reading from stdin. Call this once to begin the event loop. */
+    start() {
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => this.onData(chunk));
+        process.stdin.on('end', () => process.exit(0));
+    }
+    /** Process incoming data, splitting on newlines to handle buffered messages. */
+    async onData(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? ''; // keep incomplete last line in buffer
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const request = JSON.parse(trimmed);
+                const response = await this.handler(request);
+                if (response) {
+                    this.send(response);
+                }
+            }
+            catch {
+                this.send({
+                    jsonrpc: '2.0',
+                    id: null,
+                    error: { code: -32700, message: 'Parse error' },
+                });
+            }
+        }
+    }
+    /** Write a JSON-RPC response to stdout. */
+    send(response) {
+        process.stdout.write(JSON.stringify(response) + '\n');
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.2.0';

package/package.json

@@ -1,24 +1,39 @@
 {
   "name": "@ophirai/mcp-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
+  "mcpName": "io.github.Ophir-ai-creator/ophir",
   "description": "MCP tool server exposing Ophir agent negotiation as Model Context Protocol tools for LLM-powered agents",
   "type": "module",
+  "bin": {
+    "@ophirai/mcp-server": "dist/bin.js",
+    "ophir-mcp": "dist/bin.js"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ophirai/ophir",
+    "url": "https://github.com/Ophir-Protocol/ophir",
     "directory": "packages/mcp-server"
   },
-  "keywords": ["mcp", "model-context-protocol", "ai-agents", "negotiation", "ophir", "llm-tools"],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "negotiation",
+    "ophir",
+    "llm-tools"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest run --passWithNoTests",
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "dependencies": {
     "@ophirai/sdk": "*",
     "@ophirai/protocol": "*"