usepaso 0.1.0

package/dist/validator.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = validate;
+const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const VALID_PERMISSIONS = ['read', 'write', 'admin'];
+const VALID_INPUT_TYPES = ['string', 'integer', 'number', 'boolean', 'enum', 'array', 'object'];
+const VALID_OUTPUT_TYPES = ['string', 'integer', 'number', 'boolean', 'object', 'array'];
+const VALID_AUTH_TYPES = ['api_key', 'bearer', 'oauth2', 'none'];
+const VALID_IN_VALUES = ['query', 'path', 'body', 'header'];
+const SNAKE_CASE_RE = /^[a-z][a-z0-9_]*$/;
+/**
+ * Validate a parsed PasoDeclaration against the spec.
+ * Returns an array of errors. Empty array = valid.
+ */
+function validate(decl) {
+    const errors = [];
+    // Version
+    if (!decl.version) {
+        errors.push({ path: 'version', message: 'version is required' });
+    }
+    else if (decl.version !== '1.0') {
+        errors.push({ path: 'version', message: 'version must be "1.0"' });
+    }
+    // Service
+    if (!decl.service) {
+        errors.push({ path: 'service', message: 'service is required' });
+    }
+    else {
+        if (!decl.service.name) {
+            errors.push({ path: 'service.name', message: 'service.name is required' });
+        }
+        if (!decl.service.description) {
+            errors.push({ path: 'service.description', message: 'service.description is required' });
+        }
+        if (!decl.service.base_url) {
+            errors.push({ path: 'service.base_url', message: 'service.base_url is required' });
+        }
+        else {
+            try {
+                new URL(decl.service.base_url);
+            }
+            catch {
+                errors.push({ path: 'service.base_url', message: 'service.base_url must be a valid URL' });
+            }
+        }
+        if (decl.service.auth) {
+            if (!VALID_AUTH_TYPES.includes(decl.service.auth.type)) {
+                errors.push({ path: 'service.auth.type', message: `auth.type must be one of: ${VALID_AUTH_TYPES.join(', ')}` });
+            }
+        }
+    }
+    // Capabilities
+    if (!decl.capabilities) {
+        errors.push({ path: 'capabilities', message: 'capabilities is required' });
+    }
+    else if (!Array.isArray(decl.capabilities)) {
+        errors.push({ path: 'capabilities', message: 'capabilities must be an array' });
+    }
+    else {
+        const names = new Set();
+        decl.capabilities.forEach((cap, i) => {
+            const prefix = `capabilities[${i}]`;
+            errors.push(...validateCapability(cap, prefix, names));
+        });
+    }
+    // Permissions
+    if (decl.permissions) {
+        const capNames = new Set((decl.capabilities || []).map(c => c.name));
+        const allReferenced = new Set();
+        for (const tier of ['read', 'write', 'admin', 'forbidden']) {
+            const list = decl.permissions[tier];
+            if (list) {
+                for (const name of list) {
+                    // forbidden can reference capabilities not declared (to explicitly block API endpoints)
+                    if (tier !== 'forbidden' && !capNames.has(name)) {
+                        errors.push({ path: `permissions.${tier}`, message: `references unknown capability "${name}"` });
+                    }
+                    if (tier !== 'forbidden' && allReferenced.has(name)) {
+                        // Check if it's in forbidden
+                    }
+                    allReferenced.add(name);
+                }
+            }
+        }
+        // Check forbidden doesn't overlap with tiers
+        if (decl.permissions.forbidden) {
+            const tiered = new Set([
+                ...(decl.permissions.read || []),
+                ...(decl.permissions.write || []),
+                ...(decl.permissions.admin || []),
+            ]);
+            for (const name of decl.permissions.forbidden) {
+                if (tiered.has(name)) {
+                    errors.push({ path: 'permissions.forbidden', message: `"${name}" cannot be both in a permission tier and forbidden` });
+                }
+            }
+        }
+    }
+    return errors;
+}
+function validateCapability(cap, prefix, names) {
+    const errors = [];
+    if (!cap.name) {
+        errors.push({ path: `${prefix}.name`, message: 'name is required' });
+    }
+    else {
+        if (!SNAKE_CASE_RE.test(cap.name)) {
+            errors.push({ path: `${prefix}.name`, message: `"${cap.name}" must be snake_case` });
+        }
+        if (names.has(cap.name)) {
+            errors.push({ path: `${prefix}.name`, message: `duplicate capability name "${cap.name}"` });
+        }
+        names.add(cap.name);
+    }
+    if (!cap.description) {
+        errors.push({ path: `${prefix}.description`, message: 'description is required' });
+    }
+    if (!cap.method) {
+        errors.push({ path: `${prefix}.method`, message: 'method is required' });
+    }
+    else if (!VALID_METHODS.includes(cap.method)) {
+        errors.push({ path: `${prefix}.method`, message: `method must be one of: ${VALID_METHODS.join(', ')}` });
+    }
+    if (!cap.path) {
+        errors.push({ path: `${prefix}.path`, message: 'path is required' });
+    }
+    else if (!cap.path.startsWith('/')) {
+        errors.push({ path: `${prefix}.path`, message: 'path must start with /' });
+    }
+    if (!cap.permission) {
+        errors.push({ path: `${prefix}.permission`, message: 'permission is required' });
+    }
+    else if (!VALID_PERMISSIONS.includes(cap.permission)) {
+        errors.push({ path: `${prefix}.permission`, message: `permission must be one of: ${VALID_PERMISSIONS.join(', ')}` });
+    }
+    // Validate inputs
+    if (cap.inputs) {
+        for (const [inputName, input] of Object.entries(cap.inputs)) {
+            const inputPrefix = `${prefix}.inputs.${inputName}`;
+            if (!input.type) {
+                errors.push({ path: inputPrefix, message: 'type is required' });
+            }
+            else if (!VALID_INPUT_TYPES.includes(input.type)) {
+                errors.push({ path: inputPrefix, message: `type must be one of: ${VALID_INPUT_TYPES.join(', ')}` });
+            }
+            if (input.type === 'enum' && (!input.values || input.values.length === 0)) {
+                errors.push({ path: inputPrefix, message: 'enum type must have values defined' });
+            }
+            if (!input.description) {
+                errors.push({ path: inputPrefix, message: 'description is required' });
+            }
+            if (input.in && !VALID_IN_VALUES.includes(input.in)) {
+                errors.push({ path: `${inputPrefix}.in`, message: `in must be one of: ${VALID_IN_VALUES.join(', ')}` });
+            }
+        }
+    }
+    // Validate path params exist in inputs
+    if (cap.path && cap.inputs) {
+        const pathParams = cap.path.match(/\{([^}]+)\}/g);
+        if (pathParams) {
+            for (const param of pathParams) {
+                const paramName = param.slice(1, -1);
+                if (!cap.inputs[paramName]) {
+                    errors.push({ path: `${prefix}.path`, message: `path parameter "{${paramName}}" not found in inputs` });
+                }
+                else if (cap.inputs[paramName].in && cap.inputs[paramName].in !== 'path') {
+                    errors.push({ path: `${prefix}.inputs.${paramName}`, message: `path parameter must have in: path` });
+                }
+            }
+        }
+    }
+    // Validate output
+    if (cap.output) {
+        for (const [fieldName, output] of Object.entries(cap.output)) {
+            if (!output.type) {
+                errors.push({ path: `${prefix}.output.${fieldName}`, message: 'type is required' });
+            }
+            else if (!VALID_OUTPUT_TYPES.includes(output.type)) {
+                errors.push({ path: `${prefix}.output.${fieldName}`, message: `type must be one of: ${VALID_OUTPUT_TYPES.join(', ')}` });
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "usepaso",
+  "version": "0.1.0",
+  "description": "Make your API agent-ready in minutes. One declaration, every protocol.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "usepaso": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["ai", "agents", "mcp", "a2a", "api", "sdk", "agent-readiness"],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "yaml": "^2.7.1",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync, writeFileSync } from 'fs';
+import { parseFile } from './parser';
+import { validate } from './validator';
+import { serveMcp } from './generators/mcp';
+
+const program = new Command();
+
+program
+  .name('usepaso')
+  .description('Make your API agent-ready in minutes')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Create a paso.yaml template in the current directory')
+  .option('-n, --name <name>', 'Service name')
+  .action((opts) => {
+    const outPath = resolve('paso.yaml');
+    if (existsSync(outPath)) {
+      console.error('paso.yaml already exists in this directory.');
+      process.exit(1);
+    }
+
+    const name = opts.name || 'MyService';
+    const template = `version: "1.0"
+
+service:
+  name: ${name}
+  description: TODO — describe what your service does
+  base_url: https://api.example.com
+  auth:
+    type: bearer
+
+capabilities:
+  - name: example_action
+    description: TODO — describe what this action does
+    method: GET
+    path: /example
+    permission: read
+    inputs:
+      id:
+        type: string
+        required: true
+        description: TODO — describe this parameter
+        in: query
+    output:
+      result:
+        type: string
+        description: TODO — describe the output
+
+permissions:
+  read:
+    - example_action
+`;
+
+    writeFileSync(outPath, template, 'utf-8');
+    console.log(`Created paso.yaml for "${name}"`);
+    console.log('Edit the file to declare your API capabilities, then run: usepaso serve');
+  });
+
+program
+  .command('validate')
+  .description('Validate a paso.yaml file')
+  .option('-f, --file <path>', 'Path to paso.yaml', 'paso.yaml')
+  .action((opts) => {
+    const filePath = resolve(opts.file);
+    if (!existsSync(filePath)) {
+      console.error(`File not found: ${filePath}`);
+      process.exit(1);
+    }
+
+    try {
+      const decl = parseFile(filePath);
+      const errors = validate(decl);
+
+      if (errors.length === 0) {
+        console.log(`${filePath} is valid.`);
+        console.log(`Service: ${decl.service.name}`);
+        console.log(`Capabilities: ${decl.capabilities.length}`);
+      } else {
+        console.error(`Found ${errors.length} error(s):`);
+        for (const err of errors) {
+          console.error(`  ${err.path}: ${err.message}`);
+        }
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(`Failed to parse: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('serve')
+  .description('Start an MCP server from a paso.yaml declaration')
+  .option('-f, --file <path>', 'Path to paso.yaml', 'paso.yaml')
+  .action(async (opts) => {
+    const filePath = resolve(opts.file);
+    if (!existsSync(filePath)) {
+      console.error(`File not found: ${filePath}`);
+      process.exit(1);
+    }
+
+    try {
+      const decl = parseFile(filePath);
+      const errors = validate(decl);
+
+      if (errors.length > 0) {
+        console.error(`Validation failed with ${errors.length} error(s):`);
+        for (const err of errors) {
+          console.error(`  ${err.path}: ${err.message}`);
+        }
+        process.exit(1);
+      }
+
+      console.error(`Paso MCP server starting for "${decl.service.name}"...`);
+      console.error(`Capabilities: ${decl.capabilities.length}`);
+      console.error('Transport: stdio');
+      console.error('Waiting for MCP client connection...');
+
+      await serveMcp(decl);
+    } catch (err) {
+      console.error(`Failed to start: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/generators/mcp.ts

@@ -0,0 +1,229 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { PasoDeclaration, PasoCapability, PasoInput } from '../types';
+
+/**
+ * Generate and return an McpServer from a Paso declaration.
+ * Each capability becomes an MCP tool.
+ */
+export function generateMcpServer(decl: PasoDeclaration): McpServer {
+  const server = new McpServer({
+    name: decl.service.name,
+    version: decl.service.version || '1.0.0',
+  });
+
+  const forbidden = new Set(decl.permissions?.forbidden || []);
+
+  for (const cap of decl.capabilities) {
+    if (forbidden.has(cap.name)) continue;
+
+    const inputSchema = buildZodSchema(cap);
+    const description = buildToolDescription(cap, decl);
+
+    if (inputSchema) {
+      server.tool(cap.name, description, inputSchema, async (args) => {
+        return await executeCapability(cap, args, decl);
+      });
+    } else {
+      server.tool(cap.name, description, async () => {
+        return await executeCapability(cap, {}, decl);
+      });
+    }
+  }
+
+  return server;
+}
+
+/**
+ * Start the MCP server on stdio transport.
+ */
+export async function serveMcp(decl: PasoDeclaration): Promise<void> {
+  const server = generateMcpServer(decl);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+/**
+ * Build a Zod schema from a capability's inputs.
+ * Returns undefined if the capability has no inputs.
+ */
+function buildZodSchema(cap: PasoCapability): Record<string, z.ZodTypeAny> | undefined {
+  if (!cap.inputs || Object.keys(cap.inputs).length === 0) return undefined;
+
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [name, input] of Object.entries(cap.inputs)) {
+    let field = inputToZod(input);
+
+    if (!input.required) {
+      field = field.optional();
+    }
+
+    if (input.description) {
+      field = field.describe(input.description);
+    }
+
+    shape[name] = field;
+  }
+
+  return shape;
+}
+
+/**
+ * Convert a PasoInput to a Zod type.
+ */
+function inputToZod(input: PasoInput): z.ZodTypeAny {
+  switch (input.type) {
+    case 'string':
+      return z.string();
+    case 'integer':
+      return z.number().int();
+    case 'number':
+      return z.number();
+    case 'boolean':
+      return z.boolean();
+    case 'enum':
+      if (input.values && input.values.length > 0) {
+        const vals = input.values.map(v => String(v));
+        return z.enum(vals as [string, ...string[]]);
+      }
+      return z.string();
+    case 'array':
+      return z.array(z.unknown());
+    case 'object':
+      return z.record(z.string(), z.unknown());
+    default:
+      return z.unknown();
+  }
+}
+
+/**
+ * Build a rich tool description from the capability and service info.
+ */
+function buildToolDescription(cap: PasoCapability, decl: PasoDeclaration): string {
+  let desc = cap.description;
+
+  if (cap.consent_required) {
+    desc += '\n\n⚠️ REQUIRES USER CONSENT: You must confirm this action with the user before executing.';
+  }
+
+  if (cap.constraints && cap.constraints.length > 0) {
+    desc += '\n\nConstraints:';
+    for (const c of cap.constraints) {
+      if (c.description) desc += `\n- ${c.description}`;
+      if (c.max_per_hour) desc += `\n- Rate limit: ${c.max_per_hour}/hour`;
+      if (c.max_value) desc += `\n- Max value: ${c.max_value}`;
+      if (c.max_per_request) desc += `\n- Max per request: ${c.max_per_request}`;
+    }
+  }
+
+  return desc;
+}
+
+/**
+ * Execute a capability by making the actual HTTP request to the service.
+ */
+async function executeCapability(
+  cap: PasoCapability,
+  args: Record<string, unknown>,
+  decl: PasoDeclaration,
+): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  // Build the URL
+  let path = cap.path;
+  const queryParams: Record<string, string> = {};
+  const bodyParams: Record<string, unknown> = {};
+
+  if (cap.inputs) {
+    for (const [name, input] of Object.entries(cap.inputs)) {
+      const value = args[name];
+      if (value === undefined) continue;
+
+      const location = input.in || (
+        ['POST', 'PUT', 'PATCH'].includes(cap.method) ? 'body' : 'query'
+      );
+
+      switch (location) {
+        case 'path':
+          path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+          break;
+        case 'query':
+          queryParams[name] = String(value);
+          break;
+        case 'header':
+          // Headers handled separately
+          break;
+        case 'body':
+        default:
+          bodyParams[name] = value;
+          break;
+      }
+    }
+  }
+
+  const url = new URL(path, decl.service.base_url);
+  for (const [k, v] of Object.entries(queryParams)) {
+    url.searchParams.set(k, v);
+  }
+
+  // Build headers
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Accept': 'application/json',
+  };
+
+  if (decl.service.auth) {
+    // Auth token comes from environment variable: PASO_AUTH_TOKEN
+    const token = process.env.PASO_AUTH_TOKEN;
+    if (token) {
+      const authHeader = decl.service.auth.header || 'Authorization';
+      const prefix = decl.service.auth.prefix ?? (decl.service.auth.type === 'bearer' ? 'Bearer' : '');
+      headers[authHeader] = prefix ? `${prefix} ${token}` : token;
+    }
+  }
+
+  // Add any header-type inputs
+  if (cap.inputs) {
+    for (const [name, input] of Object.entries(cap.inputs)) {
+      if (input.in === 'header' && args[name] !== undefined) {
+        headers[name] = String(args[name]);
+      }
+    }
+  }
+
+  try {
+    const fetchOptions: RequestInit = {
+      method: cap.method,
+      headers,
+    };
+
+    if (['POST', 'PUT', 'PATCH'].includes(cap.method) && Object.keys(bodyParams).length > 0) {
+      fetchOptions.body = JSON.stringify(bodyParams);
+    }
+
+    const response = await fetch(url.toString(), fetchOptions);
+    const text = await response.text();
+
+    let result: string;
+    try {
+      const json = JSON.parse(text);
+      result = JSON.stringify(json, null, 2);
+    } catch {
+      result = text;
+    }
+
+    if (!response.ok) {
+      return {
+        content: [{ type: 'text', text: `Error ${response.status}: ${result}` }],
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: result }],
+    };
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Request failed: ${error instanceof Error ? error.message : String(error)}` }],
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { parseFile, parseString } from './parser';
+export { validate } from './validator';
+export { generateMcpServer } from './generators/mcp';
+export type {
+  PasoDeclaration,
+  PasoService,
+  PasoAuth,
+  PasoCapability,
+  PasoInput,
+  PasoOutput,
+  PasoConstraint,
+  PasoPermissions,
+  ValidationError,
+} from './types';

package/src/parser.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+import { PasoDeclaration } from './types';
+
+/**
+ * Parse a paso.yaml file from disk and return the raw declaration object.
+ * Does NOT validate — call validate() separately.
+ */
+export function parseFile(filePath: string): PasoDeclaration {
+  const content = readFileSync(filePath, 'utf-8');
+  return parseString(content);
+}
+
+/**
+ * Parse a YAML string into a PasoDeclaration.
+ */
+export function parseString(content: string): PasoDeclaration {
+  const parsed = parseYaml(content);
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Invalid YAML: expected an object');
+  }
+  return parsed as PasoDeclaration;
+}