mcpaas 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +91 -45
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,15 +1,24 @@
1
1
  # mcpaas
2
2
 
3
- TypeScript SDK for [MCPaaS](https://mcpaas.live) — Context, on-demand.
3
+ [![npm](https://img.shields.io/npm/v/mcpaas)](https://www.npmjs.com/package/mcpaas)
4
+ [![MCPaaS](https://mcpaas.live/badge/Wolfe-Jam/mcpaas-sdk.svg)](https://mcpaas.live)
4
5
 
5
- Zero dependencies. Works with Bun, Node 18+, Deno, browsers, and edge runtimes.
6
+ Typed TypeScript client for [MCPaaS](https://mcpaas.live) — the platform for AI context delivery.
7
+
8
+ Zero dependencies. Works everywhere `fetch` does: Bun, Node 18+, Deno, browsers, edge runtimes.
9
+
10
+ ## Try It
11
+
12
+ ```bash
13
+ bunx bun -e "import { MCPaaS } from './src'; const m = new MCPaaS(); console.log(await m.getRawSoul('spacex'))"
14
+ ```
6
15
 
7
16
  ## Install
8
17
 
9
18
  ```bash
10
- npm install mcpaas
11
- # or
12
19
  bun add mcpaas
20
+ # or
21
+ npm install mcpaas
13
22
  ```
14
23
 
15
24
  ## Quick Start
@@ -19,72 +28,93 @@ import { MCPaaS } from 'mcpaas';
19
28
 
20
29
  const m = new MCPaaS();
21
30
 
22
- // Read a soul
23
- const soul = await m.getRawSoul('spacex');
24
- console.log(soul);
31
+ // Read live AI context (a "soul")
32
+ const spacex = await m.getRawSoul('spacex');
33
+ // => "SpaceX — Founded 2002 by Elon Musk..."
25
34
 
26
- // Score a namepoint
27
- const result = await m.score('faf');
28
- console.log(result.score, result.tierReady);
35
+ // Score any GitHub repo's AI-readiness
36
+ const repo = await m.scoreRepo('anthropics/claude-code');
37
+ // => { score: 72, repo: "anthropics/claude-code", language: "TypeScript", ... }
29
38
 
30
- // Check handle availability
39
+ // Check if a namepoint handle is available
31
40
  const check = await m.check('myhandle');
32
- console.log(check.available);
41
+ // => { handle: "myhandle", available: true, price: "$2/month" }
42
+
43
+ // Get tag intelligence across 700+ namepoints
44
+ const intel = await m.tagIntel();
45
+ // => { tags: [...], candidates: [...], merges: [...], analysed: 721 }
33
46
  ```
34
47
 
35
- ## API
48
+ ## What MCPaaS Does
49
+
50
+ MCPaaS delivers AI context at 300+ Cloudflare edges in sub-millisecond time. The platform provides:
51
+
52
+ - **Souls** — persistent AI context blocks (project DNA, personas, live data)
53
+ - **Namepoints** — claimed handles in a global directory (like DNS for AI context)
54
+ - **Scoring** — AI-readiness scores for repos and namepoints
55
+ - **Tag Intel** — pattern detection, co-occurrence analysis, and tag suggestions
56
+ - **Globe** — real-time execution stats from 300+ edge locations
57
+ - **Badges** — SVG badges for any GitHub repo's score
58
+
59
+ This SDK wraps all 15 public endpoints into typed methods with full IntelliSense.
60
+
61
+ ## API Reference
36
62
 
37
63
  ### Souls
38
64
 
39
- ```typescript
40
- m.getSoul('faf') // Structured soul content
41
- m.getRawSoul('spacex') // Plain text soul
42
- m.listSouls() // Stats: counts, top souls, operations
43
- ```
65
+ | Method | Returns | Description |
66
+ |--------|---------|-------------|
67
+ | `getSoul(name)` | `Promise<string>` | Structured soul content |
68
+ | `getRawSoul(name)` | `Promise<string>` | Plain text soul content |
69
+ | `listSouls()` | `Promise<SoulStats>` | Total count, top souls, daily operations |
44
70
 
45
71
  ### Scoring
46
72
 
47
- ```typescript
48
- m.score('faf') // Score a namepoint
49
- m.scoreRepo('owner/repo') // Score a GitHub repo
50
- m.leaderboard() // Top scored repos
51
- ```
73
+ | Method | Returns | Description |
74
+ |--------|---------|-------------|
75
+ | `score(handle)` | `Promise<ScoreResult>` | Score a namepoint (0-100) |
76
+ | `scoreRepo(repo)` | `Promise<RepoScore>` | Score a GitHub repo's AI-readiness |
77
+ | `leaderboard()` | `Promise<LeaderboardResult>` | Top and recent scored repos |
52
78
 
53
79
  ### Directory & Discovery
54
80
 
55
- ```typescript
56
- m.directory() // Full namepoint directory
57
- m.check('handle') // Handle availability + pricing
58
- m.count() // Claimed/remaining counts
59
- m.discover() // Discovery feed (namepoints + souls)
60
- ```
81
+ | Method | Returns | Description |
82
+ |--------|---------|-------------|
83
+ | `directory()` | `Promise<DirectoryResult>` | Full namepoint directory with tag index |
84
+ | `check(handle)` | `Promise<CheckResult>` | Handle availability and pricing |
85
+ | `count()` | `Promise<CountResult>` | Claimed/remaining namepoint counts |
86
+ | `discover()` | `Promise<DiscoverResult>` | Discovery feed (namepoints + souls) |
61
87
 
62
88
  ### Tag Intel
63
89
 
64
- ```typescript
65
- m.tagIntel() // Tag patterns, co-occurrence, candidates, merges
66
- m.suggestTags('handle') // Suggest tags for a namepoint
67
- ```
90
+ | Method | Returns | Description |
91
+ |--------|---------|-------------|
92
+ | `tagIntel()` | `Promise<TagIntelResult>` | Tag patterns, co-occurrence, candidates, merge suggestions |
93
+ | `suggestTags(handle)` | `Promise<SuggestResult>` | Suggested tags for a namepoint based on content |
68
94
 
69
95
  ### Badges
70
96
 
97
+ | Method | Returns | Description |
98
+ |--------|---------|-------------|
99
+ | `badge(owner, repo)` | `string` | SVG badge URL (synchronous) |
100
+
71
101
  ```typescript
72
- m.badge('owner', 'repo') // Returns SVG badge URL (sync)
73
- // => https://mcpaas.live/badge/owner/repo.svg
102
+ m.badge('Wolfe-Jam', 'faf-cli')
103
+ // => "https://mcpaas.live/badge/Wolfe-Jam/faf-cli.svg"
74
104
  ```
75
105
 
76
106
  ### Globe
77
107
 
78
- ```typescript
79
- m.globe() // Edge location stats from 300+ Cloudflare colos
80
- ```
108
+ | Method | Returns | Description |
109
+ |--------|---------|-------------|
110
+ | `globe()` | `Promise<GlobeResult>` | Edge location execution stats from 300+ Cloudflare colos |
81
111
 
82
112
  ### Platform
83
113
 
84
- ```typescript
85
- m.health() // Health check
86
- m.info() // Server info
87
- ```
114
+ | Method | Returns | Description |
115
+ |--------|---------|-------------|
116
+ | `health()` | `Promise<HealthResult>` | Service health + engine status |
117
+ | `info()` | `Promise<InfoResult>` | Server name and version |
88
118
 
89
119
  ## Configuration
90
120
 
@@ -96,6 +126,8 @@ const m = new MCPaaS({
96
126
 
97
127
  ## Error Handling
98
128
 
129
+ All methods throw `MCPaaSError` on non-2xx responses:
130
+
99
131
  ```typescript
100
132
  import { MCPaaS, MCPaaSError } from 'mcpaas';
101
133
 
@@ -103,13 +135,27 @@ try {
103
135
  await m.getSoul('nonexistent');
104
136
  } catch (e) {
105
137
  if (e instanceof MCPaaSError) {
106
- console.log(e.status); // HTTP status code
107
- console.log(e.body); // Response body
108
- console.log(e.path); // Request path
138
+ e.status // 404
139
+ e.body // "Not found"
140
+ e.path // "/souls/nonexistent"
109
141
  }
110
142
  }
111
143
  ```
112
144
 
145
+ ## TypeScript
146
+
147
+ All response types are exported for use in your own code:
148
+
149
+ ```typescript
150
+ import type { ScoreResult, DirectoryEntry, TagIntelResult } from 'mcpaas';
151
+ ```
152
+
113
153
  ## License
114
154
 
115
155
  MIT
156
+
157
+ ## Links
158
+
159
+ - [MCPaaS Platform](https://mcpaas.live)
160
+ - [API Dashboard](https://mcpaas.live/souls/stats)
161
+ - [GitHub](https://github.com/Wolfe-Jam/mcpaas-sdk)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcpaas",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "MCPaaS SDK — Context, on-demand. Read souls, score repos, discover tags, query the globe.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",