mcpaas 0.1.0 → 1.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Wolfe James
+Copyright (c) 2026 WolfeJam
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,127 +1,161 @@
 # mcpaas
 
-**Your AI forgets you every session. MCPaaS remembers.**
+[![npm](https://img.shields.io/npm/v/mcpaas)](https://www.npmjs.com/package/mcpaas)
+[![MCPaaS](https://mcpaas.live/badge/Wolfe-Jam/mcpaas-sdk.svg)](https://mcpaas.live)
 
-You re-explain your stack to Claude. Switch to Gemini — re-explain everything. Open Cursor — again. Every session. Every tool. Every time.
+Typed TypeScript client for [MCPaaS](https://mcpaas.live) — the platform for AI context delivery.
 
-That's the drift tax. [$49M/day](https://fafdev.tools/value) burned industry-wide.
+Zero dependencies. Works everywhere `fetch` does: Bun, Node 18+, Deno, browsers, edge runtimes.
 
-This SDK connects you to [MCPaaS](https://mcpaas.live) — persistent AI context that follows you across tools, sessions, and teams.
+## Try It
+
+```bash
+bunx bun -e "import { MCPaaS } from './src'; const m = new MCPaaS(); console.log(await m.getRawSoul('spacex'))"
+```
 
 ## Install
 
 ```bash
+bun add mcpaas
+# or
 npm install mcpaas
 ```
 
 ## Quick Start
 
 ```typescript
-import { Radio } from 'mcpaas';
+import { MCPaaS } from 'mcpaas';
 
-const radio = new Radio('wss://mcpaas.live/beacon/radio');
-await radio.connect();
+const m = new MCPaaS();
 
-// Tune to your project's frequency
-await radio.tune('91.0');
+// Read live AI context (a "soul")
+const spacex = await m.getRawSoul('spacex');
+// => "SpaceX — Founded 2002 by Elon Musk..."
 
-// Your context arrives — from any AI, any session
-radio.onBroadcast((frequency, context) => {
-  console.log(`Context update on ${frequency} FM:`, context);
-});
+// Score any GitHub repo's AI-readiness
+const repo = await m.scoreRepo('anthropics/claude-code');
+// => { score: 72, repo: "anthropics/claude-code", language: "TypeScript", ... }
+
+// Check if a namepoint handle is available
+const check = await m.check('myhandle');
+// => { handle: "myhandle", available: true, price: "$2/month" }
+
+// Get tag intelligence across 700+ namepoints
+const intel = await m.tagIntel();
+// => { tags: [...], candidates: [...], merges: [...], analysed: 721 }
 ```
 
-That's it. Your context persists. Zero drift.
+## What MCPaaS Does
 
-## How It Works
+MCPaaS delivers AI context at 300+ Cloudflare edges in sub-millisecond time. The platform provides:
 
-MCPaaS uses the **Radio Protocol** — broadcast once, every AI receives.
+- **Souls** — persistent AI context blocks (project DNA, personas, live data)
+- **Namepoints** — claimed handles in a global directory (like DNS for AI context)
+- **Scoring** — AI-readiness scores for repos and namepoints
+- **Tag Intel** — pattern detection, co-occurrence analysis, and tag suggestions
+- **Globe** — real-time execution stats from 300+ edge locations
+- **Badges** — SVG badges for any GitHub repo's score
 
-```
-Traditional (the tax):
-  You → Claude  (send 50KB context)
-  You → Grok    (send 50KB again)
-  You → Gemini  (send 50KB again)
-  = 3x cost, 3x latency, context drift
-
-Radio Protocol (the fix):
-  You → Broadcast to 91.0 FM (send once)
-  Claude  ← tuned to 91.0
-  Grok    ← tuned to 91.0
-  Gemini  ← tuned to 91.0
-  = 1x cost, instant, zero drift
-```
+This SDK wraps all 15 public endpoints into typed methods with full IntelliSense.
 
-## Multi-AI Example
+## API Reference
 
-```typescript
-import { Radio } from 'mcpaas';
+### Souls
 
-const claude = new Radio('wss://mcpaas.live/beacon/radio');
-const grok   = new Radio('wss://mcpaas.live/beacon/radio');
-const gemini = new Radio('wss://mcpaas.live/beacon/radio');
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getSoul(name)` | `Promise<string>` | Structured soul content |
+| `getRawSoul(name)` | `Promise<string>` | Plain text soul content |
+| `listSouls()` | `Promise<SoulStats>` | Total count, top souls, daily operations |
 
-await Promise.all([claude.connect(), grok.connect(), gemini.connect()]);
-await Promise.all([claude.tune('91.0'), grok.tune('91.0'), gemini.tune('91.0')]);
+### Scoring
 
-// All three AIs now share the same context, in real time
-claude.onBroadcast((f, ctx) => console.log('Claude:', ctx));
-grok.onBroadcast((f, ctx)   => console.log('Grok:', ctx));
-gemini.onBroadcast((f, ctx) => console.log('Gemini:', ctx));
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `score(handle)` | `Promise<ScoreResult>` | Score a namepoint (0-100) |
+| `scoreRepo(repo)` | `Promise<RepoScore>` | Score a GitHub repo's AI-readiness |
+| `leaderboard()` | `Promise<LeaderboardResult>` | Top and recent scored repos |
+
+### Directory & Discovery
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `directory()` | `Promise<DirectoryResult>` | Full namepoint directory with tag index |
+| `check(handle)` | `Promise<CheckResult>` | Handle availability and pricing |
+| `count()` | `Promise<CountResult>` | Claimed/remaining namepoint counts |
+| `discover()` | `Promise<DiscoverResult>` | Discovery feed (namepoints + souls) |
 
-## API
+### Tag Intel
 
-### Constructor
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `tagIntel()` | `Promise<TagIntelResult>` | Tag patterns, co-occurrence, candidates, merge suggestions |
+| `suggestTags(handle)` | `Promise<SuggestResult>` | Suggested tags for a namepoint based on content |
+
+### Badges
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `badge(owner, repo)` | `string` | SVG badge URL (synchronous) |
 
 ```typescript
-const radio = new Radio(url: string, options?: {
-  reconnect?: boolean;           // Auto-reconnect (default: true)
-  maxReconnectAttempts?: number; // Max attempts (default: 5)
-  reconnectDelay?: number;       // Delay in ms (default: 1000)
-  heartbeatInterval?: number;    // Ping interval (default: 30000)
-  debug?: boolean;               // Debug logging (default: false)
-});
+m.badge('Wolfe-Jam', 'faf-cli')
+// => "https://mcpaas.live/badge/Wolfe-Jam/faf-cli.svg"
 ```
 
-### Methods
+### Globe
 
-| Method | Description |
-|--------|-------------|
-| `connect()` | Connect to MCPaaS |
-| `tune(frequency)` | Subscribe to a frequency |
-| `untune(frequency)` | Unsubscribe from a frequency |
-| `disconnect()` | Disconnect |
-| `getState()` | `'DISCONNECTED'` \| `'CONNECTING'` \| `'CONNECTED'` \| `'RECONNECTING'` \| `'CLOSED'` |
-| `getTunedFrequencies()` | Set of tuned frequencies |
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `globe()` | `Promise<GlobeResult>` | Edge location execution stats from 300+ Cloudflare colos |
 
-### Events
+### Platform
 
-| Event | Callback |
-|-------|----------|
-| `onBroadcast(fn)` | `(frequency, context) => void` |
-| `onConnect(fn)` | `() => void` |
-| `onDisconnect(fn)` | `(code?, reason?) => void` |
-| `onError(fn)` | `(error) => void` |
-| `onTuned(fn)` | `(frequency) => void` |
-| `onUntuned(fn)` | `(frequency) => void` |
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `health()` | `Promise<HealthResult>` | Service health + engine status |
+| `info()` | `Promise<InfoResult>` | Server name and version |
+
+## Configuration
+
+```typescript
+const m = new MCPaaS({
+  baseUrl: 'https://mcpaas.live',  // default
+});
+```
 
-## Why Bun?
+## Error Handling
 
-Anthropic acquired Bun in December 2025. Bun now powers Claude Code. This library is built for Bun first — native TypeScript, 7x faster WebSockets, zero config.
+All methods throw `MCPaaSError` on non-2xx responses:
 
-## Namepoints
+```typescript
+import { MCPaaS, MCPaaSError } from 'mcpaas';
+
+try {
+  await m.getSoul('nonexistent');
+} catch (e) {
+  if (e instanceof MCPaaSError) {
+    e.status  // 404
+    e.body    // "Not found"
+    e.path    // "/souls/nonexistent"
+  }
+}
+```
 
-Every frequency maps to a **namepoint** on MCPaaS — your permanent AI identity.
+## TypeScript
 
-Free namepoints work. But `yourname.mcpaas.live` hits different than `user-38291.mcpaas.live`.
+All response types are exported for use in your own code:
 
-**Claim yours before someone else does:** [mcpaas.live/claim](https://mcpaas.live/claim)
+```typescript
+import type { ScoreResult, DirectoryEntry, TagIntelResult } from 'mcpaas';
+```
 
 ## License
 
 MIT
 
----
+## Links
 
-Built by [Wolfe James](https://github.com/Wolfe-Jam) | Powered by [MCPaaS](https://mcpaas.live) | Format: [FAF](https://faf.one)
+- [MCPaaS Platform](https://mcpaas.live)
+- [API Dashboard](https://mcpaas.live/souls/stats)
+- [GitHub](https://github.com/Wolfe-Jam/mcpaas-sdk)

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * MCPaaS SDK — Context, on-demand.
+ * =================================
+ * Zero-dependency TypeScript client for the MCPaaS platform.
+ * Works with Bun, Node 18+, Deno, browsers, and edge runtimes.
+ *
+ * Usage:
+ *   import { MCPaaS } from 'mcpaas';
+ *   const m = new MCPaaS();
+ *   const soul = await m.getRawSoul('spacex');
+ */
+export interface MCPaaSOptions {
+    /** Base URL of the MCPaaS instance. Default: https://mcpaas.live */
+    baseUrl?: string;
+}
+export interface SoulStats {
+    date: string;
+    total_souls: number;
+    operations_today: Record<string, number>;
+    top_souls: Array<{
+        soul: string;
+        reads: number;
+    }>;
+}
+export interface ScoreResult {
+    handle: string;
+    score: number;
+    tierReady: boolean;
+    valid: boolean;
+    engine: string;
+}
+export interface RepoScore {
+    score: number;
+    repo: string;
+    hasFaf: boolean;
+    language: string;
+    stars: number;
+    description: string;
+}
+export interface LeaderboardResult {
+    top: Array<{
+        repo: string;
+        score: number;
+        language: string;
+    }>;
+    recent: Array<{
+        repo: string;
+        score: number;
+        language: string;
+    }>;
+    total: number;
+}
+export interface DirectoryEntry {
+    handle: string;
+    name: string;
+    tagline: string;
+    role: string;
+    avatar: number;
+    tags: string[];
+    userTags: string[];
+    score: number;
+}
+export interface DirectoryResult {
+    count: number;
+    namepoints: DirectoryEntry[];
+    userTagIndex: Array<{
+        tag: string;
+        count: number;
+    }>;
+}
+export interface CheckResult {
+    handle: string;
+    available: boolean;
+    price?: number;
+    tier?: string;
+}
+export interface CountResult {
+    claimed: number;
+    remaining: number;
+    tier: string;
+    price: string;
+    annual: string;
+    names: string[];
+}
+export interface DiscoverResult {
+    namepoints: DirectoryEntry[];
+    souls: string[];
+    totalSouls: number;
+}
+export interface TagProfile {
+    tag: string;
+    count: number;
+    cooccurs: Array<{
+        tag: string;
+        overlap: number;
+    }>;
+}
+export interface TagCandidate {
+    term: string;
+    count: number;
+    source: string;
+}
+export interface TagMerge {
+    canonical: string;
+    variants: string[];
+}
+export interface TagIntelResult {
+    tags: TagProfile[];
+    candidates: TagCandidate[];
+    merges: TagMerge[];
+    analysed: number;
+    updatedAt: string;
+}
+export interface SuggestResult {
+    handle: string;
+    existingTags: string[];
+    suggestions: string[];
+}
+export interface GlobeLocation {
+    code: string;
+    count: number;
+    lat: number;
+    lng: number;
+    city: string;
+    active: boolean;
+}
+export interface GlobeResult {
+    total: number;
+    activeLocations: number;
+    totalLocations: number;
+    locations: GlobeLocation[];
+    updated: string;
+}
+export interface HealthResult {
+    status: string;
+    engine: string;
+    engineStatus: string;
+    engineScore: number;
+    engineSize: string;
+    [key: string]: unknown;
+}
+export interface InfoResult {
+    name: string;
+    version: string;
+    [key: string]: unknown;
+}
+export declare class MCPaaS {
+    private baseUrl;
+    constructor(options?: MCPaaSOptions);
+    /** Fetch structured soul content by name */
+    getSoul(name: string): Promise<string>;
+    /** Fetch raw plain-text soul content */
+    getRawSoul(name: string): Promise<string>;
+    /** Get soul stats (counts, top souls, operations) */
+    listSouls(): Promise<SoulStats>;
+    /** Score a namepoint by handle */
+    score(handle: string): Promise<ScoreResult>;
+    /** Score a GitHub repo (owner/repo or full URL) */
+    scoreRepo(repo: string): Promise<RepoScore>;
+    /** Get the scoring leaderboard */
+    leaderboard(): Promise<LeaderboardResult>;
+    /** Get the full namepoint directory */
+    directory(): Promise<DirectoryResult>;
+    /** Check if a handle is available */
+    check(handle: string): Promise<CheckResult>;
+    /** Get namepoint counts */
+    count(): Promise<CountResult>;
+    /** Discovery feed (namepoints + souls) */
+    discover(): Promise<DiscoverResult>;
+    /** Full tag intelligence: patterns, co-occurrence, candidates, merges */
+    tagIntel(): Promise<TagIntelResult>;
+    /** Suggest tags for a namepoint based on content patterns */
+    suggestTags(handle: string): Promise<SuggestResult>;
+    /** Get the badge URL for a GitHub repo (synchronous — returns URL string) */
+    badge(owner: string, repo: string): string;
+    /** Get edge location execution stats from 300+ Cloudflare colos */
+    globe(): Promise<GlobeResult>;
+    /** Health check */
+    health(): Promise<HealthResult>;
+    /** Server info */
+    info(): Promise<InfoResult>;
+    private json;
+    private text;
+}
+export declare class MCPaaSError extends Error {
+    status: number;
+    body: string;
+    path: string;
+    constructor(status: number, body: string, path: string);
+}
+export default MCPaaS;