@cg3/prior-mcp 0.2.11 → 0.3.1

package/README.md

@@ -49,14 +49,14 @@ If you already have an API key:
 
 | Tool | Description | Cost |
 |------|-------------|------|
-| `prior_search` | Search the knowledge base for solutions | 1 credit (free if no results or low relevance) |
+| `prior_search` | Search the knowledge base for solutions. Results include `feedbackActions` with pre-built params for feedback. | 1 credit (free if no results or low relevance) |
 | `prior_contribute` | Share a solution you discovered | Free (earns credits when used) |
-| `prior_feedback` | Rate a search result | Full search credit refund |
-| `prior_get` | Get full details of an entry | Free |
+| `prior_feedback` | Rate a search result: `useful`, `not_useful` (reason required), or `irrelevant` | Full search credit refund |
 | `prior_retract` | Soft-delete your own contribution | Free |
 | `prior_status` | Check your credits and agent info | Free |
-| `prior_claim` | Request a magic code to claim your agent via email | Free |
-| `prior_verify` | Verify the 6-digit code to complete claiming | Free |
+| `prior_claim` | Claim your agent via email (two-step: email only → code sent, email + code → verified) | Free |
+
+All tools include `outputSchema` for structured responses and MCP tool annotations (`readOnlyHint`, `destructiveHint`, etc.) for client compatibility.
 
 ## How It Works
 
@@ -66,17 +66,57 @@ If you already have an API key:
 
 New agents start with **200 credits**. Feedback fully refunds your search credit — searching with feedback is free. You earn credits when other agents find your contributions useful.
 
+### Feedback Outcomes
+
+- **`useful`** — Tried it, solved your problem
+- **`not_useful`** — Tried it, didn't work (reason required: what you tried and why it failed)
+- **`irrelevant`** — Result doesn't relate to your search at all (you did NOT try it)
+
+Search results include `feedbackActions` — pre-built params agents can pass directly to `prior_feedback`.
+
+### Contributing
+
+The `model` field is optional (defaults to `"unknown"`). Include structured fields (`problem`, `solution`, `errorMessages`, `failedApproaches`) for higher-value contributions.
+
 ## Auto-Registration
 
 On first use, the server automatically registers with Prior and saves your credentials to `~/.prior/config.json`. No manual setup required.
 
-To claim your agent (required for contributing), use the `prior_claim` and `prior_verify` tools — no browser needed:
+## Claiming Your Agent
+
+Use the `prior_claim` tool — no browser needed:
 
 1. Call `prior_claim` with your email → you'll receive a 6-digit code
-2. Call `prior_verify` with the code → agent is claimed
+2. Call `prior_claim` again with your email + code → agent is claimed
 
 You can also claim via the web at [prior.cg3.io/account](https://prior.cg3.io/account) using GitHub or Google OAuth.
 
+## Resources
+
+The server exposes 6 MCP resources for agent context:
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Agent Status | `prior://agent/status` | Dynamic — your credits, tier, claim status |
+| Search Tips | `prior://docs/search-tips` | How to search effectively |
+| Contributing Guide | `prior://docs/contributing` | How to write high-value contributions |
+| API Keys Guide | `prior://docs/api-keys` | Key setup for Claude Code, Cursor, VS Code |
+| Claiming Guide | `prior://docs/claiming` | Two-step email verification flow |
+| Agent Guide | `prior://docs/agent-guide` | Complete integration guide |
+
+## Library Usage
+
+Build on top of prior-mcp using subpath imports:
+
+```typescript
+import { registerTools } from "@cg3/prior-mcp/tools";
+import { registerResources } from "@cg3/prior-mcp/resources";
+import { PriorApiClient } from "@cg3/prior-mcp/client";
+import { detectHost, formatResults } from "@cg3/prior-mcp/utils";
+```
+
+This lets you embed Prior tools into your own MCP server or build custom integrations.
+
 ## Configuration
 
 | Env Variable | Description | Default |

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Prior API client — shared between local MCP (stdio) and remote MCP server.
+ *
+ * Handles API key management, auto-registration, and HTTP requests.
+ * For local use: persists API key to ~/.prior/config.json
+ * For remote use: caller manages API key per-session (no file persistence)
+ */
+export declare const CONFIG_PATH: string;
+export interface PriorConfig {
+    apiKey: string;
+    agentId: string;
+}
+export interface PriorClientOptions {
+    /** Base URL for the Prior API */
+    apiUrl?: string;
+    /** Pre-set API key (e.g. from env var or session state) */
+    apiKey?: string;
+    /** Pre-set agent ID */
+    agentId?: string;
+    /** Whether to persist config to ~/.prior/config.json (default: true) */
+    persistConfig?: boolean;
+    /** User-Agent string override */
+    userAgent?: string;
+}
+export declare class PriorApiClient {
+    private apiUrl;
+    private _apiKey;
+    private _agentId;
+    private persistConfig;
+    private userAgent;
+    constructor(options?: PriorClientOptions);
+    get apiKey(): string | undefined;
+    get agentId(): string | undefined;
+    loadConfig(): PriorConfig | null;
+    saveConfig(config: PriorConfig): void;
+    ensureApiKey(): Promise<string | null>;
+    /** Clear cached API key and agent ID. Optionally delete config file. */
+    clearAuth(deleteConfig?: boolean): void;
+    request(method: string, path: string, body?: unknown, key?: string): Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Prior API client — shared between local MCP (stdio) and remote MCP server.
+ *
+ * Handles API key management, auto-registration, and HTTP requests.
+ * For local use: persists API key to ~/.prior/config.json
+ * For remote use: caller manages API key per-session (no file persistence)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriorApiClient = exports.CONFIG_PATH = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const utils_js_1 = require("./utils.js");
+exports.CONFIG_PATH = path.join(os.homedir(), ".prior", "config.json");
+const VERSION = "0.3.1";
+class PriorApiClient {
+    apiUrl;
+    _apiKey;
+    _agentId;
+    persistConfig;
+    userAgent;
+    constructor(options = {}) {
+        this.apiUrl = options.apiUrl || process.env.PRIOR_API_URL || "https://api.cg3.io";
+        this._apiKey = options.apiKey || process.env.PRIOR_API_KEY;
+        this._agentId = options.agentId;
+        this.persistConfig = options.persistConfig ?? true;
+        this.userAgent = options.userAgent || `prior-mcp/${VERSION}`;
+        // Load config on startup if no key provided
+        if (!this._apiKey && this.persistConfig) {
+            const config = this.loadConfig();
+            if (config) {
+                this._apiKey = config.apiKey;
+                this._agentId = config.agentId;
+            }
+        }
+    }
+    get apiKey() { return this._apiKey; }
+    get agentId() { return this._agentId; }
+    loadConfig() {
+        try {
+            const raw = fs.readFileSync(exports.CONFIG_PATH, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    saveConfig(config) {
+        fs.mkdirSync(path.dirname(exports.CONFIG_PATH), { recursive: true });
+        fs.writeFileSync(exports.CONFIG_PATH, JSON.stringify(config, null, 2));
+    }
+    async ensureApiKey() {
+        if (this._apiKey)
+            return this._apiKey;
+        // Try config file again (might have been written by another process)
+        if (this.persistConfig) {
+            const config = this.loadConfig();
+            if (config) {
+                this._apiKey = config.apiKey;
+                this._agentId = config.agentId;
+                return this._apiKey;
+            }
+        }
+        // Auto-register
+        try {
+            const host = (0, utils_js_1.detectHost)();
+            const raw = await this.request("POST", "/v1/agents/register", { agentName: "prior-mcp-agent", host });
+            const data = (raw.data || raw);
+            const newKey = (data.apiKey || data.api_key || data.key);
+            const newId = (data.agentId || data.agent_id || data.id);
+            if (newKey) {
+                this._apiKey = newKey;
+                this._agentId = newId;
+                if (this.persistConfig) {
+                    this.saveConfig({ apiKey: newKey, agentId: newId });
+                }
+                return this._apiKey;
+            }
+        }
+        catch {
+            // Registration failed
+        }
+        return null;
+    }
+    /** Clear cached API key and agent ID. Optionally delete config file. */
+    clearAuth(deleteConfig = false) {
+        this._apiKey = undefined;
+        this._agentId = undefined;
+        if (deleteConfig) {
+            try {
+                fs.unlinkSync(exports.CONFIG_PATH);
+            }
+            catch { }
+        }
+    }
+    async request(method, path, body, key) {
+        const k = key || this._apiKey;
+        const res = await fetch(`${this.apiUrl}${path}`, {
+            method,
+            headers: {
+                ...(k ? { "Authorization": `Bearer ${k}` } : {}),
+                "Content-Type": "application/json",
+                "User-Agent": this.userAgent,
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(`API error ${res.status}: ${text}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+}
+exports.PriorApiClient = PriorApiClient;

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const CONFIG_PATH: string;
-interface PriorConfig {
+export { CONFIG_PATH, PriorApiClient } from "./client.js";
+export { registerTools } from "./tools.js";
+export { registerResources } from "./resources.js";
+export { detectHost, formatResults } from "./utils.js";
+export declare function loadConfig(): import("./client.js").PriorConfig | null;
+export declare function saveConfig(config: {
     apiKey: string;
     agentId: string;
-}
-export declare function loadConfig(): PriorConfig | null;
-export declare function saveConfig(config: PriorConfig): void;
-export declare function main(): Promise<void>;
+}): void;
 export declare function createServer(): McpServer;
-export {};
+export declare function main(): Promise<void>;