@oriva/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @oriva/mcp-server
+
+Model Context Protocol server for the [Oriva](https://api.oriva.io) public API.
+
+Exposes all 46 public Oriva API endpoints as MCP tools so AI agents (Claude Code, Cursor, Continue, Claude Desktop) can read and write Oriva data on behalf of a user with an `oriva_pk_*` API key.
+
+## Install + connect (Claude Code)
+
+```bash
+claude mcp add oriva npx -- -y @oriva/mcp-server -e ORIVA_API_KEY=oriva_pk_xxx
+```
+
+Then in any Claude Code session, `/mcp` lists `oriva` and you can ask things like:
+
+- "use oriva to show my current user"
+- "list my marketplace apps with oriva"
+- "create an Oriva event titled 'Demo Day' on 2026-06-01"
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `ORIVA_API_KEY` | yes | Bearer key for `Authorization` header. Get one from https://api.oriva.io/developer |
+| `ORIVA_API_BASE_URL` | no | Override the API base URL (default `https://api.oriva.io`). Useful for local development against a tunnel. |
+
+## What's exposed
+
+Every public Oriva API endpoint that the OpenAPI spec marks with an `operationId` becomes an MCP tool with the same name. Path + required query parameters are flagged required; optional query params and JSON body fields are optional. Response bodies come back verbatim as text content.
+
+### Coverage
+
+- 46 operations across 40 paths
+- Read + write surfaces: profiles, groups, sessions, marketplace, developer, entries, events, auth/profile, analytics, users
+- v1 supports `application/json` requests + responses only. Multipart, octet-stream, and server-sent events are **not** wired (the projector throws at boot if the spec adds them).
+
+### Excluded by design
+
+- First-party tenant routes (`/api/v1/tenant/*`) — never part of the public contract
+- Internal debug / dev routes (`/dev-profiles`, `/api/v1/debug/cors`)
+- Admin routes that require a separate `requireAdminToken`
+
+The complete list lives in `claudedocs/public-api-contract.md` in the o-platform repo.
+
+## How tools are derived
+
+This server hand-rolls a projection from `o-platform/claudedocs/openapi-snapshot.json` at build time. The snapshot is bundled into `dist/spec.json`, so `npx` consumers don't need the repo. When the spec changes upstream, `npm run build` re-bundles and re-projects with zero hand edits.
+
+Mapping:
+
+| OpenAPI | MCP |
+|---|---|
+| `operationId` | `tools/list[].name` |
+| `summary` + `description` | `tools/list[].description` |
+| `parameters[in=path]` | required input field |
+| `parameters[in=query]` | required iff `required: true` |
+| `requestBody.content['application/json'].schema` | flattened into input fields |
+| 2xx response body | `CallToolResult.content[0].text` (verbatim) |
+| Non-2xx | `isError: true` with HTTP status prefix |
+
+Path-param vs body-field name collisions are resolved with path-param wins; the body field gets a `body_` prefix.
+
+## Develop locally
+
+```bash
+git clone https://github.com/0riva/o-platform.git
+cd o-platform/packages/mcp-server
+npm install
+npm run build
+ORIVA_API_KEY=oriva_pk_xxx npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) gives you a web UI to list and call tools without needing an LLM client.
+
+To add the locally-built server to Claude Code:
+
+```bash
+claude mcp add oriva-dev node $PWD/dist/index.js -e ORIVA_API_KEY=oriva_pk_xxx
+```
+
+## License
+
+MIT — see [LICENSE](../../LICENSE) in the o-platform repo root.

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import type { ProjectedOperation } from './types.js';
+export interface CallResult {
+    status: number;
+    text: string;
+    ok: boolean;
+}
+export interface ClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export declare function callOperation(op: ProjectedOperation, args: Record<string, unknown>, options: ClientOptions): Promise<CallResult>;

package/dist/client.js

@@ -0,0 +1,55 @@
+const DEFAULT_BASE_URL = 'https://api.oriva.io';
+export async function callOperation(op, args, options) {
+    const baseUrl = options.baseUrl ?? process.env.ORIVA_API_BASE_URL ?? DEFAULT_BASE_URL;
+    let path = op.path;
+    for (const name of op.pathParams) {
+        const value = args[name];
+        if (value === undefined || value === null) {
+            throw new Error(`Missing required path parameter: ${name}`);
+        }
+        path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+    }
+    const qs = new URLSearchParams();
+    for (const name of op.queryParams) {
+        const value = args[name];
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                qs.append(name, String(item));
+        }
+        else {
+            qs.set(name, String(value));
+        }
+    }
+    const queryString = qs.toString();
+    let body;
+    let contentType;
+    const methodAllowsBody = op.method !== 'get' && op.method !== 'head' && op.method !== 'delete';
+    if (methodAllowsBody && op.bodyFields.length > 0) {
+        const bodyObj = {};
+        for (const { alias, original } of op.bodyFields) {
+            if (args[alias] !== undefined)
+                bodyObj[original] = args[alias];
+        }
+        if (Object.keys(bodyObj).length > 0) {
+            body = JSON.stringify(bodyObj);
+            contentType = 'application/json';
+        }
+    }
+    const url = `${baseUrl}${path}${queryString ? '?' + queryString : ''}`;
+    const headers = {
+        Authorization: `Bearer ${options.apiKey}`,
+        Accept: 'application/json',
+        'User-Agent': '@oriva/mcp-server/0.1.0',
+    };
+    if (contentType)
+        headers['Content-Type'] = contentType;
+    const res = await fetch(url, {
+        method: op.method.toUpperCase(),
+        headers,
+        body,
+    });
+    const text = await res.text();
+    return { status: res.status, text, ok: res.ok };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { callOperation } from './client.js';
+import { getSpecInfo, projectTools } from './openapi.js';
+const PKG_NAME = '@oriva/mcp-server';
+const PKG_VERSION = '0.1.0';
+function fail(message) {
+    process.stderr.write(`[oriva-mcp] ${message}\n`);
+    process.exit(1);
+}
+const apiKey = process.env.ORIVA_API_KEY;
+if (!apiKey) {
+    fail('ORIVA_API_KEY environment variable is required.\n' +
+        '         Get a key from https://api.oriva.io/developer and run with:\n' +
+        '           ORIVA_API_KEY=oriva_pk_xxx oriva-mcp');
+}
+let projection;
+try {
+    projection = projectTools();
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fail(`Failed to project OpenAPI spec into MCP tools: ${message}`);
+}
+const { tools, index } = projection;
+const info = getSpecInfo();
+process.stderr.write(`[oriva-mcp] Loaded ${tools.length} tools from spec (${info.paths} paths, ${info.schemas} schemas).\n`);
+const server = new Server({ name: PKG_NAME, version: PKG_VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const op = index.get(request.params.name);
+    if (!op) {
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await callOperation(op, request.params.arguments ?? {}, { apiKey });
+        const prefix = result.ok ? '' : `HTTP ${result.status}\n`;
+        return {
+            content: [{ type: 'text', text: `${prefix}${result.text}` }],
+            isError: !result.ok,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write('[oriva-mcp] Connected via stdio.\n');

package/dist/openapi.d.ts

@@ -0,0 +1,10 @@
+import type { MCPTool, OperationIndex } from './types.js';
+export interface ProjectionResult {
+    tools: MCPTool[];
+    index: OperationIndex;
+}
+export declare function projectTools(): ProjectionResult;
+export declare function getSpecInfo(): {
+    paths: number;
+    schemas: number;
+};

package/dist/openapi.js

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+const ANNOTATION_KEYS = [
+    'type',
+    'description',
+    'enum',
+    'format',
+    'pattern',
+    'minimum',
+    'maximum',
+    'minLength',
+    'maxLength',
+    'example',
+    'items',
+    'nullable',
+    'default',
+];
+function loadSpec() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const specPath = resolve(here, 'spec.json');
+    const raw = readFileSync(specPath, 'utf-8');
+    return JSON.parse(raw);
+}
+const SPEC = loadSpec();
+function resolveRef(node, seen = new Set()) {
+    if (!node || typeof node !== 'object')
+        return {};
+    if (node.$ref && typeof node.$ref === 'string') {
+        if (seen.has(node.$ref))
+            return {}; // cycle guard
+        const nextSeen = new Set(seen);
+        nextSeen.add(node.$ref);
+        const path = node.$ref.replace(/^#\//, '').split('/');
+        let resolved = SPEC;
+        for (const segment of path) {
+            resolved = resolved?.[segment];
+        }
+        if (!resolved) {
+            throw new Error(`Unresolved $ref: ${node.$ref}`);
+        }
+        return resolveRef(resolved, nextSeen);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        if (k === 'properties' && v && typeof v === 'object') {
+            const props = {};
+            for (const [pk, pv] of Object.entries(v)) {
+                props[pk] = resolveRef(pv, new Set(seen));
+            }
+            out.properties = props;
+        }
+        else if (k === 'items' && v && typeof v === 'object') {
+            out.items = resolveRef(v, new Set(seen));
+        }
+        else if (k === 'additionalProperties' && v && typeof v === 'object') {
+            out.additionalProperties = resolveRef(v, new Set(seen));
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function preserveAnnotations(schema, param) {
+    const out = {};
+    for (const key of ANNOTATION_KEYS) {
+        const value = schema[key];
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    if (param?.description && !out.description)
+        out.description = param.description;
+    if (!out.type)
+        out.type = 'string';
+    return out;
+}
+function buildInputSchema(op) {
+    const properties = {};
+    const required = [];
+    const pathParams = [];
+    const queryParams = [];
+    const bodyFields = [];
+    for (const p of op.parameters ?? []) {
+        if (p.in !== 'path' && p.in !== 'query')
+            continue;
+        const resolved = p.schema ? resolveRef(p.schema) : {};
+        properties[p.name] = preserveAnnotations(resolved, p);
+        if (p.in === 'path') {
+            pathParams.push(p.name);
+            if (!required.includes(p.name))
+                required.push(p.name);
+        }
+        else {
+            queryParams.push(p.name);
+            if (p.required && !required.includes(p.name))
+                required.push(p.name);
+        }
+    }
+    const bodySchema = op.requestBody?.content?.['application/json']?.schema;
+    if (bodySchema) {
+        const resolvedBody = resolveRef(bodySchema);
+        const bodyRequired = new Set(resolvedBody.required ?? []);
+        const bodyIsRequired = op.requestBody?.required === true;
+        for (const [key, sub] of Object.entries(resolvedBody.properties ?? {})) {
+            const collision = key in properties;
+            const alias = collision ? `body_${key}` : key;
+            properties[alias] = resolveRef(sub);
+            bodyFields.push({ alias, original: key });
+            const isRequired = bodyRequired.has(key) || (bodyIsRequired && bodyRequired.size === 0);
+            if (isRequired && !required.includes(alias))
+                required.push(alias);
+        }
+    }
+    return {
+        schema: { type: 'object', properties, required, additionalProperties: false },
+        operation: { pathParams, queryParams, bodyFields },
+    };
+}
+export function projectTools() {
+    const tools = [];
+    const index = new Map();
+    const seenNames = new Set();
+    for (const [path, methods] of Object.entries(SPEC.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const op = methods[method];
+            if (!op?.operationId)
+                continue;
+            if (seenNames.has(op.operationId)) {
+                throw new Error(`Duplicate operationId in spec: ${op.operationId}`);
+            }
+            seenNames.add(op.operationId);
+            const { schema, operation } = buildInputSchema(op);
+            const description = [op.summary, op.description].filter(Boolean).join(' — ') ||
+                `${method.toUpperCase()} ${path}`;
+            tools.push({ name: op.operationId, description, inputSchema: schema });
+            index.set(op.operationId, {
+                toolName: op.operationId,
+                path,
+                method,
+                ...operation,
+            });
+        }
+    }
+    return { tools, index };
+}
+export function getSpecInfo() {
+    return {
+        paths: Object.keys(SPEC.paths ?? {}).length,
+        schemas: Object.keys(SPEC.components?.schemas ?? {}).length,
+    };
+}

package/dist/spec.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"Oriva Platform API","version":"1.0.0","description":"Public API for 3rd party Oriva developers. Authenticate with your API key as a Bearer token."},"servers":[{"url":"https://api.oriva.io","description":"Production"},{"url":"http://localhost:3002","description":"Local BFF proxy"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"API key with oriva_pk_ prefix"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"AuthSessionResponse":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"display_name":{"type":["string","null"]},"username":{"type":["string","null"]},"subscription_tier":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","email","display_name","username","subscription_tier","created_at"]},"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_in":{"type":"integer"}},"required":["user","access_token","refresh_token","expires_in"]},"AuthProfileResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":["string","null"],"format":"email"},"displayName":{"type":"string"},"avatar":{"type":["string","null"],"format":"uri"},"authType":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"lastLogin":{"type":"string","format":"date-time"},"accountStatus":{"type":"string"},"twoFactorEnabled":{"type":"boolean"},"emailVerified":{"type":"boolean"}},"required":["id","email","displayName","avatar","authType","permissions","lastLogin","accountStatus","twoFactorEnabled","emailVerified"]}},"required":["ok","success","data"]},"RawProfileResponse":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":["string","null"]},"username":{"type":["string","null"]},"bio":{"type":["string","null"]},"avatar_url":{"type":["string","null"],"format":"uri"},"location":{"type":["string","null"]},"website_url":{"type":["string","null"],"format":"uri"}},"required":["id","display_name","username","bio","avatar_url","location","website_url"]},"TokenRefreshResponse":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_in":{"type":"integer"}},"required":["access_token","refresh_token","expires_in"]},"ProfileSummary":{"type":"object","properties":{"profileId":{"type":"string","example":"ext_a1b2c3d4e5f6a7b8"},"profileName":{"type":"string"},"isActive":{"type":"boolean"},"avatar":{"type":["string","null"],"format":"uri"},"isDefault":{"type":"boolean"}},"required":["profileId","profileName","isActive","avatar","isDefault"]},"UpdatedProfile":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","properties":{"profileId":{"type":"string"},"profileName":{"type":"string"},"isActive":{"type":"boolean"},"avatar":{"type":["string","null"],"format":"uri"},"bio":{"type":["string","null"]},"location":{"type":["string","null"]},"updatedAt":{"type":"string","format":"date-time"}},"required":["profileId","profileName","isActive","avatar","bio","location","updatedAt"]},"message":{"type":"string"}},"required":["ok","success","data"]},"GroupSummary":{"type":"object","properties":{"groupId":{"type":"string","format":"uuid"},"groupName":{"type":"string"},"memberCount":{"type":"integer"},"isActive":{"type":"boolean"},"role":{"type":"string","example":"admin"},"description":{"type":["string","null"]},"image_url":{"type":["string","null"],"format":"uri"},"external_link":{"type":["string","null"],"format":"uri"}},"required":["groupId","groupName","memberCount","isActive","role","description","image_url","external_link"]},"GroupMember":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"role":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"},"avatar":{"type":["string","null"],"format":"uri"}},"required":["memberId","displayName","role","joinedAt","avatar"]},"UserMe":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":["string","null"]},"displayName":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"bio":{"type":["string","null"]},"location":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"avatar":{"type":["string","null"],"format":"uri"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"apiKeyInfo":{"type":"object","properties":{"keyId":{"type":"string"},"name":{"type":"string"},"userId":{"type":"string","format":"uuid"},"permissions":{"type":"array","items":{"type":"string"}},"usageCount":{"type":"integer"}},"required":["keyId","name","userId","permissions","usageCount"]}},"required":["id","username","displayName","email","bio","location","website","avatar","createdAt","updatedAt","apiKeyInfo"]}},"required":["ok","success","data"]},"AnalyticsSummary":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","properties":{"overview":{"type":"object","properties":{"totalEntries":{"type":"integer"},"totalResponses":{"type":"integer"},"totalGroups":{"type":"integer"},"installedApps":{"type":"integer"}},"required":["totalEntries","totalResponses","totalGroups","installedApps"]},"metrics":{"type":"object","properties":{"entriesGrowth":{"type":"string"},"responseGrowth":{"type":"string"},"groupActivity":{"type":"string"},"appUsage":{"type":"string"}},"required":["entriesGrowth","responseGrowth","groupActivity","appUsage"]},"recentActivity":{"type":"array","items":{}},"timeRange":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]}},"required":["overview","metrics","recentActivity","timeRange"]},"message":{"type":"string"}},"required":["ok","success","data"]},"TeamMember":{"type":"object","properties":{"profileId":{"type":"string","format":"uuid"},"displayName":{"type":["string","null"]},"username":{"type":["string","null"]},"avatarUrl":{"type":["string","null"],"format":"uri"},"role":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"},"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["profileId","displayName","username","avatarUrl","role","joinedAt","group"]},"MarketplaceApp":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"tagline":{"type":["string","null"]},"description":{"type":["string","null"]},"category":{"type":"string"},"icon_url":{"type":["string","null"],"format":"uri"},"screenshots":{"type":["array","null"],"items":{"type":"string","format":"uri"}},"version":{"type":"string"},"pricing_model":{"type":"string"},"pricing_config":{"type":["object","null"],"additionalProperties":{}},"install_count":{"type":"integer"},"developer_id":{"type":"string","format":"uuid"},"developer_name":{"type":"string"},"status":{"type":"string","enum":["draft","pending_review","approved","rejected"]},"is_active":{"type":"boolean"},"supported_audience":{"type":["array","null"],"items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","slug","category","version","pricing_model","install_count","developer_id","developer_name","status","is_active","created_at","updated_at"]},"InstalledApp":{"type":"object","properties":{"installationId":{"type":"string","format":"uuid"},"installedAt":{"type":"string","format":"date-time"},"isActive":{"type":"boolean"},"settings":{"type":["object","null"],"additionalProperties":{}},"app":{"$ref":"#/components/schemas/MarketplaceApp"}},"required":["installationId","installedAt","isActive","settings","app"]},"MarketplaceItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":["string","null"]},"profile_id":{"type":"string","format":"uuid"},"entry_type":{"type":"string"},"marketplace_metadata":{"type":["object","null"],"additionalProperties":{}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","title","profile_id","entry_type","created_at","updated_at"]},"Category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"collection_type":{"type":"string"},"organization_rules":{"type":["object","null"],"additionalProperties":{}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","collection_type","created_at","updated_at"]},"Entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string"},"profile_id":{"type":"string","format":"uuid"},"audience_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","title","content","profile_id","audience_type","created_at","updated_at"]},"Event":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"location":{"type":["string","null"]},"isOnline":{"type":"boolean"},"category":{"type":"string"},"organizer":{"type":"string","format":"uuid"},"maxAttendees":{"type":["integer","null"]},"currentAttendees":{"type":["integer","null"]},"price":{"type":"number","minimum":0},"tags":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":["string","null"],"format":"uri"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","title","description","startDate","endDate","location","isOnline","category","organizer","maxAttendees","currentAttendees","price","tags","imageUrl","createdAt","updatedAt"]},"CreatedPersonalToken":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"token":{"type":"string","description":"Full token value — displayed ONCE. Store it now; it cannot be retrieved again."},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"First 20 characters of the token, safe to display later."},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}},"required":["token","id","name","prefix","created_at","expires_at"]}},"required":["ok","success","data"]},"PersonalTokenSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"is_active":{"type":"boolean"}},"required":["id","name","prefix","created_at","last_used_at","expires_at","is_active"]},"PersonalTokenList":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PersonalTokenSummary"}}},"required":["ok","success","data"]}},"parameters":{}},"paths":{"/api/v1/auth/register":{"post":{"operationId":"register","tags":["Auth"],"summary":"Register a new user","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"pattern":"[A-Z]"},"name":{"type":"string"},"username":{"type":"string"},"preferences":{}},"required":["email","password"]}}}},"responses":{"201":{"description":"User registered and session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthSessionResponse"}}}},"400":{"description":"Validation error — weak password or invalid email"},"409":{"description":"Email already registered"}}}},"/api/v1/auth/login":{"post":{"operationId":"login","tags":["Auth"],"summary":"Log in","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1}},"required":["email","password"]}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthSessionResponse"}}}},"400":{"description":"Validation error — missing email or password"},"401":{"description":"Invalid credentials"}}}},"/api/v1/auth/logout":{"post":{"operationId":"logout","tags":["Auth"],"summary":"Log out","description":"Invalidates the current session. Requires Authorization header.","security":[{"BearerAuth":[]}],"responses":{"204":{"description":"Logged out"},"401":{"description":"Missing authorization header"}}}},"/api/v1/auth/token/refresh":{"post":{"operationId":"refreshToken","tags":["Auth"],"summary":"Refresh access token","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","minLength":1}},"required":["refresh_token"]}}}},"responses":{"200":{"description":"New tokens issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRefreshResponse"}}}},"400":{"description":"Validation error — missing refresh_token"},"401":{"description":"Invalid or expired refresh token"}}}},"/api/v1/auth/profile":{"get":{"operationId":"getAuthProfile","tags":["Auth"],"summary":"Get auth profile","description":"Returns the authenticated user identity and API key metadata.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Auth profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthProfileResponse"}}}},"401":{"description":"Unauthorized"}}},"patch":{"operationId":"patchAuthProfile","tags":["Auth"],"summary":"Update profile (partial)","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"bio":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"location":{"type":"string"},"website_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Updated profile row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawProfileResponse"}}}},"400":{"description":"No fields provided"},"401":{"description":"Unauthorized"}}},"put":{"operationId":"putAuthProfile","tags":["Auth"],"summary":"Update profile (full)","description":"Superset of PATCH — also accepts preferences and data_retention_days (min 30).","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"bio":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"location":{"type":"string"},"website_url":{"type":"string","format":"uri"},"preferences":{"type":"object","additionalProperties":{}},"data_retention_days":{"type":"integer","minimum":30}}}}}},"responses":{"200":{"description":"Updated profile row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawProfileResponse"}}}},"400":{"description":"No fields provided, or data_retention_days < 30"},"401":{"description":"Unauthorized"}}}},"/api/v1/auth/account":{"delete":{"operationId":"deleteAccount","tags":["Auth"],"summary":"Delete account","security":[{"BearerAuth":[]}],"responses":{"204":{"description":"Account deleted"},"401":{"description":"Unauthorized"}}}},"/api/v1/profiles/available":{"get":{"operationId":"listProfiles","tags":["Profiles"],"summary":"List available profiles","description":"Returns all non-anonymous active profiles for the authenticated API key.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Available profiles","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfileSummary"}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/profiles/active":{"get":{"operationId":"getActiveProfile","tags":["Profiles"],"summary":"Get active profile","description":"Returns the default active (non-anonymous) profile for the authenticated API key.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Active profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ProfileSummary"}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/profiles/{profileId}":{"put":{"operationId":"updateProfile","tags":["Profiles"],"summary":"Update a profile","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^ext_[a-f0-9]{16}$","example":"ext_a1b2c3d4e5f6a7b8"},"required":true,"name":"profileId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"profileName":{"type":"string","minLength":1},"avatar":{"type":"string","format":"uri"},"bio":{"type":["string","null"]},"location":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedProfile"}}}},"400":{"description":"Validation error — invalid profileId format or body"},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/profiles/{profileId}/activate":{"post":{"operationId":"activateProfile","tags":["Profiles"],"summary":"Activate a profile","description":"Switches the active profile to the specified profile.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^ext_[a-f0-9]{16}$","example":"ext_a1b2c3d4e5f6a7b8"},"required":true,"name":"profileId","in":"path"}],"responses":{"200":{"description":"Profile activated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","properties":{"activeProfile":{"type":"string"},"switchedAt":{"type":"string","format":"date-time"}},"required":["activeProfile","switchedAt"]}},"required":["ok","success","data"]}}}},"400":{"description":"Validation error — invalid profileId format"},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/groups":{"get":{"operationId":"listGroups","tags":["Groups"],"summary":"List groups","description":"Returns all groups the authenticated user created or joined.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"User groups","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GroupSummary"}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/groups/{groupId}/members":{"get":{"operationId":"listGroupMembers","tags":["Groups"],"summary":"Get group members","description":"Returns members of a group. Requires the caller to be the creator or a member.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"required":true,"name":"groupId","in":"path"}],"responses":{"200":{"description":"Group members","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GroupMember"}}},"required":["ok","success","data"]}}}},"400":{"description":"Validation error — invalid groupId format"},"401":{"description":"Invalid or missing API key"},"403":{"description":"Not a member or creator of this group"},"404":{"description":"Group not found"}}}},"/api/v1/user/me":{"get":{"operationId":"getCurrentUser","tags":["User"],"summary":"Get current user","description":"Returns the authenticated user's active profile and API key metadata.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Current user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMe"}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/analytics/summary":{"get":{"operationId":"getAnalyticsSummary","tags":["Analytics"],"summary":"Get analytics summary","description":"Returns 7-day usage analytics for the authenticated API key.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Analytics summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSummary"}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/sessions":{"get":{"operationId":"listSessions","tags":["Sessions"],"summary":"List sessions","description":"Returns the user's sessions. Sessions feature is not yet implemented — returns empty paginated list.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Sessions list (currently always empty)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]},"message":{"type":"string"}},"required":["ok","success","data","meta"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/sessions/upcoming":{"get":{"operationId":"listUpcomingSessions","tags":["Sessions"],"summary":"List upcoming sessions","description":"Returns upcoming sessions. Sessions feature is not yet implemented — returns empty list.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Upcoming sessions (currently always empty)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{}},"message":{"type":"string"}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/team/members":{"get":{"operationId":"listTeamMembers","tags":["Team"],"summary":"List team members","description":"Returns group memberships for the authenticated user as a flat list of team members.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Team members","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"roles":{"type":"array","items":{"type":"string"}}},"required":["total","roles"]}},"required":["ok","success","data","meta"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/marketplace/apps":{"get":{"operationId":"listMarketplaceApps","tags":["Marketplace"],"summary":"Browse marketplace apps","description":"Returns paginated list of approved, active marketplace apps.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Marketplace apps","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceApp"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]}},"required":["ok","success","data","meta"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/marketplace/trending":{"get":{"operationId":"listTrendingApps","tags":["Marketplace"],"summary":"Trending apps","description":"Returns approved apps sorted by install count (top 20).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Trending apps","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceApp"}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/marketplace/featured":{"get":{"operationId":"listFeaturedApps","tags":["Marketplace"],"summary":"Featured apps","description":"Returns featured approved apps (curated subset of top apps).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Featured apps","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceApp"}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/marketplace/categories":{"get":{"operationId":"listMarketplaceCategories","tags":["Marketplace"],"summary":"List app categories","description":"Returns distinct categories from approved apps with their app counts. Note: a second registration of this path exists (no auth, collections-table version) but is shadowed by this route (Express first-match).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Category counts","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"count":{"type":"integer"}},"required":["category","count"]}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/marketplace/apps/{appId}":{"get":{"operationId":"getMarketplaceApp","tags":["Marketplace"],"summary":"Get app details","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App details","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceApp"}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"App not found"}}}},"/api/v1/marketplace/installed":{"get":{"operationId":"listInstalledApps","tags":["Marketplace"],"summary":"List installed apps","description":"Returns all apps installed by the authenticated user.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Installed apps","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/InstalledApp"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]}},"required":["ok","success","data","meta"]}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/marketplace/install/{appId}":{"post":{"operationId":"installMarketplaceApp","tags":["Marketplace"],"summary":"Install app","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","additionalProperties":{}}}}}}},"responses":{"200":{"description":"App installed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/InstalledApp"},"message":{"type":"string"}},"required":["ok","success","data","message"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"App not found or not available for installation"},"409":{"description":"App already installed"}}}},"/api/v1/marketplace/uninstall/{appId}":{"delete":{"operationId":"uninstallMarketplaceApp","tags":["Marketplace"],"summary":"Uninstall app","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App uninstalled","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"message":{"type":"string"}},"required":["ok","success","message"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"App installation not found"}}}},"/api/v1/marketplace/items":{"get":{"operationId":"listMarketplaceItems","tags":["Marketplace"],"summary":"List marketplace items","description":"Public listing of published marketplace items (entry-based). No authentication required.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string"},"required":false,"name":"item_type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"earner_type","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"category_id","in":"query"},{"schema":{"type":"number"},"required":false,"name":"min_price","in":"query"},{"schema":{"type":"number"},"required":false,"name":"max_price","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"seller_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Marketplace items","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceItem"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]}},"required":["ok","success","data","meta"]}}}}}}},"/api/v1/marketplace/items/{id}":{"get":{"operationId":"getMarketplaceItem","tags":["Marketplace"],"summary":"Get marketplace item","description":"Returns a single published marketplace item by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Marketplace item","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceItem"}},"required":["ok","success","data"]}}}},"404":{"description":"Item not found"}}}},"/api/v1/marketplace/search":{"post":{"operationId":"searchMarketplace","tags":["Marketplace"],"summary":"Search marketplace","description":"Full-text search across marketplace items. No authentication required.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1},"filters":{"type":"object","additionalProperties":{}},"limit":{"type":"integer","maximum":100},"offset":{"type":"integer"}},"required":["query"]}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceItem"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]}},"required":["ok","success","data","meta"]}}}}}}},"/api/v1/marketplace/categories/tree":{"get":{"operationId":"getCategoryTree","tags":["Marketplace"],"summary":"Category tree","description":"Returns marketplace categories as a hierarchical tree from the collections table. Children are nested category objects of the same shape.","responses":{"200":{"description":"Category tree","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Category"},{"type":"object","properties":{"children":{"type":"array","items":{"type":"object","additionalProperties":{}}}}}]}}},"required":["ok","success","data"]}}}}}}},"/api/v1/marketplace/categories/{id}":{"get":{"operationId":"getMarketplaceCategory","tags":["Marketplace"],"summary":"Get category","description":"Returns a single marketplace category from the collections table.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Category","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Category"}},"required":["ok","success","data"]}}}},"404":{"description":"Category not found"}}}},"/api/v1/developer/apps":{"get":{"operationId":"listDeveloperApps","tags":["Developer"],"summary":"List developer apps","description":"Returns all marketplace apps owned by the authenticated developer.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Developer apps","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceApp"}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}},"post":{"operationId":"createDeveloperApp","tags":["Developer"],"summary":"Create app","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"tagline":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","minLength":1},"icon_url":{"type":"string","format":"uri"},"screenshots":{"type":"array","items":{"type":"string","format":"uri"}},"version":{"type":"string","default":"1.0.0"},"pricing_model":{"type":"string","default":"free"},"pricing_config":{"type":"object","additionalProperties":{}},"supported_audience":{"type":"array","items":{"type":"string"}}},"required":["name","slug","category"]}}}},"responses":{"201":{"description":"App created (status: draft)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceApp"}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/developer/apps/{appId}":{"get":{"operationId":"getDeveloperApp","tags":["Developer"],"summary":"Get developer app","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App details","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceApp"}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"App not found or not owned by this developer"}}},"put":{"operationId":"updateDeveloperApp","tags":["Developer"],"summary":"Update app","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"tagline":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"icon_url":{"type":"string","format":"uri"},"screenshots":{"type":"array","items":{"type":"string","format":"uri"}},"version":{"type":"string"},"pricing_model":{"type":"string"},"pricing_config":{"type":"object","additionalProperties":{}},"supported_audience":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"App updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceApp"}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"App not found or not owned by this developer"}}},"delete":{"operationId":"deleteDeveloperApp","tags":["Developer"],"summary":"Delete app","description":"Only draft apps can be deleted. Approved apps must be deactivated first.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"responses":{"204":{"description":"App deleted"},"400":{"description":"App is not in draft status — cannot delete"},"401":{"description":"Invalid or missing API key"},"404":{"description":"App not found or not owned by this developer"}}}},"/api/v1/developer/apps/{appId}/submit":{"post":{"operationId":"submitDeveloperApp","tags":["Developer"],"summary":"Submit app for review","description":"Transitions app from draft → pending_review.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App submitted for review","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceApp"},"message":{"type":"string"}},"required":["ok","success","data","message"]}}}},"400":{"description":"App is not in draft status"},"401":{"description":"Invalid or missing API key"},"404":{"description":"App not found or not owned by this developer"}}}},"/api/v1/developer/apps/{appId}/resubmit":{"post":{"operationId":"resubmitDeveloperApp","tags":["Developer"],"summary":"Resubmit rejected app","description":"Updates fields and resubmits a rejected app for review.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"tagline":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"icon_url":{"type":"string","format":"uri"},"screenshots":{"type":"array","items":{"type":"string","format":"uri"}},"version":{"type":"string"},"pricing_model":{"type":"string"},"pricing_config":{"type":"object","additionalProperties":{}},"supported_audience":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"App resubmitted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketplaceApp"},"message":{"type":"string"}},"required":["ok","success","data","message"]}}}},"400":{"description":"App is not in rejected status"},"401":{"description":"Invalid or missing API key"},"404":{"description":"App not found or not owned by this developer"}}}},"/api/v1/entries":{"get":{"operationId":"listEntries","tags":["Entries"],"summary":"List entries","description":"Returns paginated entries for the authenticated user's profile.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Entries list","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]}},"required":["ok","success","data","meta"]}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"User profile not found"}}}},"/api/v1/templates":{"get":{"operationId":"listTemplates","tags":["Entries"],"summary":"List templates","description":"Returns available entry templates. Not yet implemented — returns empty list.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Templates list (currently always empty)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["pagination"]}},"required":["ok","success","data","meta"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/storage":{"get":{"operationId":"getStorage","tags":["Entries"],"summary":"Get storage info","description":"Returns storage usage for the authenticated user. Not yet implemented — returns empty object.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Storage info","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","additionalProperties":{}}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/v1/ui/notifications":{"post":{"operationId":"createUiNotification","tags":["UI"],"summary":"Create notification","description":"Creates a UI notification for the authenticated user.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Notification created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["ok","success","data"]}}}},"401":{"description":"Invalid or missing API key"}}}},"/api/oriva/events":{"get":{"operationId":"listEvents","tags":["Events"],"summary":"List events","description":"Returns active events with optional filtering by category and date range.","parameters":[{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"integer","maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Events list","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["ok","success","data","total","limit","offset"]}}}}}},"post":{"operationId":"createEvent","tags":["Events"],"summary":"Create event","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"isOnline":{"type":"boolean"},"category":{"type":"string","minLength":1},"location":{"type":["string","null"]},"maxAttendees":{"type":["integer","null"],"exclusiveMinimum":0},"price":{"type":"number","minimum":0},"tags":{"type":"array","items":{"type":"string"},"maxItems":20},"imageUrl":{"type":["string","null"],"format":"uri"}},"required":["title","description","startDate","endDate","isOnline","category"]}}}},"responses":{"201":{"description":"Event created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Event"},"message":{"type":"string"}},"required":["ok","success","data","message"]}}}},"400":{"description":"Validation error — missing required fields or invalid category"},"401":{"description":"Unauthorized"}}}},"/api/oriva/events/{eventId}":{"get":{"operationId":"getEvent","tags":["Events"],"summary":"Get event","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"eventId","in":"path"}],"responses":{"200":{"description":"Event details","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Event"}},"required":["ok","success","data"]}}}},"404":{"description":"Event not found"}}}},"/api/v1/me/tokens":{"post":{"operationId":"createPersonalAccessToken","tags":["PersonalTokens"],"summary":"Create a Personal Access Token","description":"Issues a new Personal Access Token (PAT) scoped to the authenticated account. The full token value is returned **once** and cannot be retrieved again. PATs carry broad `[\"read\",\"write\"]` permissions and are intended for personal tooling (e.g. MCP servers).","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable label for the token"},"expires_at":{"type":"string","format":"date-time","description":"ISO 8601 expiry date. Omit for a non-expiring token."}},"required":["name"]}}}},"responses":{"201":{"description":"Token created — contains the full one-time token value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedPersonalToken"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"}}},"get":{"operationId":"listPersonalAccessTokens","tags":["PersonalTokens"],"summary":"List Personal Access Tokens","description":"Returns all PATs belonging to the authenticated account. Full token values and hashes are never returned.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of PATs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalTokenList"}}}},"401":{"description":"Not authenticated"}}}},"/api/v1/me/tokens/{id}":{"delete":{"operationId":"revokePersonalAccessToken","tags":["PersonalTokens"],"summary":"Revoke a Personal Access Token","description":"Sets `is_active = false` on the token (soft-delete). The row is preserved for audit purposes. Returns 404 if the token does not belong to this account.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Revoked successfully"},"401":{"description":"Not authenticated"},"404":{"description":"Token not found or does not belong to this account"}}}}},"webhooks":{}}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options';
+export interface JsonSchema {
+    type?: string | string[];
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    enum?: unknown[];
+    format?: string;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    example?: unknown;
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    nullable?: boolean;
+    default?: unknown;
+    $ref?: string;
+    [k: string]: unknown;
+}
+export interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+}
+export interface ProjectedOperation {
+    toolName: string;
+    path: string;
+    method: HttpMethod;
+    pathParams: string[];
+    queryParams: string[];
+    bodyFields: Array<{
+        alias: string;
+        original: string;
+    }>;
+}
+export type OperationIndex = Map<string, ProjectedOperation>;
+export interface OpenApiParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    schema?: JsonSchema;
+    description?: string;
+}
+export interface OpenApiOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        required?: boolean;
+        content?: Record<string, {
+            schema?: JsonSchema;
+        }>;
+    };
+}
+export type OpenApiPaths = Record<string, Partial<Record<HttpMethod, OpenApiOperation>>>;
+export interface OpenApiDoc {
+    paths: OpenApiPaths;
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+    };
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@oriva/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the Oriva public API. Exposes all 46 public endpoints as MCP tools for use in Claude Code, Cursor, Continue, and Claude Desktop.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "oriva-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "prebuild": "node scripts/copy-spec.mjs",
+    "build": "tsc && node scripts/post-build.mjs",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0riva/o-platform.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://api.oriva.io",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "oriva",
+    "claude",
+    "ai-tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}