auxilo-mcp 0.9.1 → 0.9.2

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 (8) hide show
  1. package/README.md +130 -149
  2. package/bin/auxilo-cli.js +230 -68
  3. package/lib/installer.js +5 -1
  4. package/lib/review.js +170 -3
  5. package/mcp-server.js +243 -146
  6. package/package.json +11 -2
  7. package/scripts/extract-local.js +119 -0
  8. package/scripts/runner.js +10 -8
package/README.md CHANGED
@@ -1,201 +1,182 @@
1
1
  # Auxilo
2
2
 
3
- Agent capability discovery and knowledge marketplace. Find the right tool for any task. Learn from what other agents already figured out.
3
+ [![npm version](https://img.shields.io/npm/v/auxilo-mcp)](https://www.npmjs.com/package/auxilo-mcp)
4
+ [![npm downloads](https://img.shields.io/npm/dm/auxilo-mcp)](https://www.npmjs.com/package/auxilo-mcp)
5
+ [![license](https://img.shields.io/npm/l/auxilo-mcp)](LICENSE)
4
6
 
5
- **Live API**: `https://api.auxilo.io`
7
+ Auxilo is an MCP server that auto-extracts operational learnings from your coding agent's sessions, gives your agent its own learnings back free in every later session, and lists them in a marketplace where other agents pay to unlock them.
6
8
 
7
- ## What it does
9
+ Your agent stops solving the same problem twice. When another agent unlocks what yours figured out, you earn.
8
10
 
9
- Auxilo solves two problems for AI agents:
11
+ ## The problem
10
12
 
11
- 1. **Skill Discovery** — Search 30 skills across 8 categories (APIs, MCP servers) to find the right tool for any task. Get connection details, auth requirements, and pricing in one query.
13
+ Your agent hits a rate limit, finds the workaround, and ships. Next session it hits the same rate limit and burns the same twenty minutes, because the fix lived in a conversation that no longer exists. Agents re-solve solved problems every day.
12
14
 
13
- 2. **Knowledge Marketplace** — Agents share operational learnings from real tasks. What worked, what failed, what the docs don't tell you. Contributors earn a 70% revenue share when others unlock their knowledge directly (60% via discovery).
15
+ Training data does not cover this. LLMs know what was in their training data. Auxilo knows what agents discovered last week.
16
+
17
+ And this is different from memory tools: mem0 is a memory you build. Auxilo is a memory that builds itself from your agent's work.
14
18
 
15
19
  ## Quick start
16
20
 
17
- ### HTTP API
21
+ ```bash
22
+ npx auxilo setup
23
+ ```
24
+
25
+ One command. It finds your installed MCP clients, registers the server in each, and signs you in with a device code. At the end it asks whether to enable background extraction. That prompt defaults to no. Decline and you still have every marketplace tool; extraction stays off until you opt in.
26
+
27
+ Then ask your agent: "Search Auxilo for Firecrawl rate limit learnings" or "Contribute what we just figured out to Auxilo."
28
+
29
+ ## How extraction works
30
+
31
+ Enable extraction and a session-end hook runs when your agent finishes a session:
32
+
33
+ 1. The hook hands the runner the path to the session transcript.
34
+ 2. The runner reads the transcript on your machine and scrubs it with a fail-closed secret filter: 24 patterns covering API keys, tokens, private keys, JWTs, connection strings, cookies, email addresses, phone numbers, and internal IPs. If a rescan still finds a match, the run stops and nothing is sent.
35
+ 3. Your own model client (your claude CLI, on your subscription) drafts learnings from the scrubbed text and screens them again.
36
+ 4. Clean drafts publish to the marketplace with a 7-day retraction window. Anything a screen flags waits in your private pending queue instead.
37
+
38
+ ### What never leaves your machine
39
+
40
+ Your raw transcripts. They are read and scrubbed on your machine, and they are never sent to Auxilo. The extraction step processes the scrubbed text through your own model provider (your claude CLI, your subscription), exactly like your normal agent sessions. The only thing sent to Auxilo is the finished learning draft.
41
+
42
+ ### How publishing works
43
+
44
+ Extraction defaults to seamless: a draft that passes every screen (secrets, sensitivity, injection, near-duplicate, quality) publishes right away, and you can retract it for 7 days. A draft that any screen flags waits in a pending queue only you can see.
18
45
 
19
46
  ```bash
20
- # Free — check what's available
21
- curl https://api.auxilo.io/categories
47
+ npx auxilo review # approve, reject, or skip each queued draft
48
+ npx auxilo status # clients, hooks, queue depth, consent state
49
+ npx auxilo disable # kill switch: extraction stops immediately
50
+ ```
22
51
 
23
- # Free — marketplace stats
24
- curl https://api.auxilo.io/knowledge/stats
52
+ Approve a queued draft and it goes live in the marketplace. Reject it and it stays private. Prefer approve-first for everything? Switch your account to manual mode in account settings and every draft waits for you.
25
53
 
26
- # Free — submit a learning
27
- curl -X POST https://api.auxilo.io/learn \
28
- -H "Content-Type: application/json" \
29
- -d '{
30
- "title": "E2B sessions timeout after 5 min idle",
31
- "body": "Send a no-op command every 3 minutes to keep alive...",
32
- "category": "code-execution",
33
- "tags": ["e2b", "sandbox", "timeout"],
34
- "task_context": "Running long code generation tasks",
35
- "outcome": "workaround",
36
- "contributor_wallet": "0xYOUR_WALLET"
37
- }'
38
-
39
- # Discovery and search are FREE — no payment required
40
- # /discover — Free
41
- # /skill/:id — Free
42
- # /knowledge — Free
43
- # /knowledge/:id — dynamic price set by algorithm (min $0.005, 70% to contributor)
54
+ Extraction off? Your agent can still contribute in-session: tell it to submit a learning with the `auxilo_contribute` tool.
55
+
56
+ ## Per-client setup
57
+
58
+ `npx auxilo setup` detects and configures every client below. To configure by hand:
59
+
60
+ **Claude Code**
61
+
62
+ ```bash
63
+ claude mcp add auxilo -- npx auxilo-mcp
44
64
  ```
45
65
 
46
- ### MCP Server (Claude Desktop)
66
+ **Claude Desktop**
47
67
 
48
- Add to your Claude Desktop config (`claude_desktop_config.json`):
68
+ Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
49
69
 
50
70
  ```json
51
71
  {
52
72
  "mcpServers": {
53
73
  "auxilo": {
54
- "command": "node",
55
- "args": ["/path/to/auxilo/mcp-server.js"]
74
+ "command": "npx",
75
+ "args": ["auxilo-mcp"]
56
76
  }
57
77
  }
58
78
  }
59
79
  ```
60
80
 
61
- Then ask Claude: *"Search Auxilo for an email API"* or *"Find knowledge about Firecrawl rate limits"*
62
-
63
- **MCP Tools (v0.7.0):**
64
-
65
- *Auxilo Core*
66
- - `auxilo_discover` — Search the skills registry
67
- - `auxilo_skill` — Get full details for a specific skill
68
- - `auxilo_categories` — List all categories
69
- - `auxilo_stats` — Registry statistics
70
- - `auxilo_contribute` — Submit a learning (free, earn revenue)
71
- - `auxilo_knowledge` — Search knowledge base
72
- - `auxilo_unlock` — Read full learning content
73
- - `auxilo_rate` — Rate a learning after using it
74
- - `auxilo_contributor` — Check contributor earnings
75
- - `auxilo_verify_wallet` — Wallet ownership verification flow
76
- - `auxilo_withdraw` — Request withdrawal of earned USDC
77
- - `auxilo_settlements` — Check settlement history for a wallet
78
- - `auxilo_link_wallet` — Link a verified wallet to your account
79
- - `auxilo_account_earnings` — View earnings for your authenticated account
80
-
81
- *Renderly (v0.7.0 — new)*
82
- - `renderly_markdown` — Convert any public URL to clean markdown ($0.001)
83
- - `renderly_extract` — Extract structured data from any URL ($0.001)
84
- - `renderly_readable` — Get plain readable text from any URL ($0.0005)
85
- - `renderly_llms_txt` — Get the LLM-readable Renderly service description (free)
86
- - `renderly_health` — Check Renderly service health (free)
87
- - `renderly_pricing` — Get Renderly pricing info (free)
88
-
89
- *Stats (v0.7.0 — new)*
90
- - `get_stats` — Registry statistics (alias, free)
91
- - `get_knowledge_stats` — Knowledge marketplace statistics (free)
92
-
93
- ## Skill categories
94
-
95
- | Category | Skills | Examples |
96
- |---|---|---|
97
- | data-processing | 6 | Jina Reader, Firecrawl, Serper, Pinecone |
98
- | storage-state | 7 | Upstash Redis, Cloudflare KV, Supabase |
99
- | code-execution | 4 | E2B Sandbox, Conway Cloud |
100
- | communication | 3 | Resend Email, Twilio, Slack |
101
- | web-interaction | 3 | Browserbase, Firecrawl Crawl |
102
- | content-generation | 3 | Replicate, ElevenLabs |
103
- | payment-financial | 2 | Stripe, x402 |
104
- | monitoring | 2 | BetterStack, Sentry |
81
+ **Cursor**
105
82
 
106
- ## Knowledge marketplace
83
+ The same `mcpServers` block in `~/.cursor/mcp.json`.
107
84
 
108
- Agents learn things the hard way — rate limits, undocumented behavior, workarounds. That knowledge usually dies with the session. Auxilo captures it.
85
+ **Windsurf**
109
86
 
110
- **How it works:**
111
- 1. **Contribute** (free) — Submit what you learned. Set your own unlock price (min $0.005).
112
- 2. **Search** (free) — Find relevant learnings. Returns titles, snippets, and unlock prices.
113
- 3. **Unlock** (dynamic) — Read the full learning. Price set by contributor. 70% goes to them.
114
- 4. **Rate** (free) — Rate helpfulness 1-5. Higher-rated learnings rank higher.
87
+ The same `mcpServers` block in `~/.codeium/windsurf/mcp_config.json`.
115
88
 
116
- Contributors earn a revenue share every time another agent unlocks their knowledge.
89
+ **Any other MCP client**
117
90
 
118
- ## Payments
91
+ The same block works anywhere MCP configs are read. The installer also detects Codex CLI, Gemini CLI, Antigravity, Factory, Copilot CLI, Continue, opencode, Kiro, Junie, Amp, and OpenHands.
119
92
 
120
- All paid endpoints use [x402](https://www.x402.org) — HTTP-native micropayments.
93
+ ## Tools
121
94
 
122
- - **Network**: Base (eip155:8453)
123
- - **Asset**: USDC
124
- - **Facilitator**: `https://facilitator.openx402.ai`
95
+ 18 tools:
125
96
 
126
- Agents with x402-compatible wallets include the `X-Payment` header. No accounts, no API keys, no subscriptions.
97
+ | Tool | What it does | Cost |
98
+ |---|---|---|
99
+ | `auxilo_knowledge` | Search marketplace learnings; returns snippets and unlock prices | Free |
100
+ | `auxilo_unlock` | Read a learning's full content | $0.05 to $50, set per learning; your own learnings $0 |
101
+ | `auxilo_contribute` | Submit a learning from the current session | Free |
102
+ | `auxilo_review` | List, approve, or reject your own pending-review learnings | Free |
103
+ | `auxilo_rate` | Rate a learning 1 to 5 after applying it | Free |
104
+ | `auxilo_discover` | Search the skills registry for APIs and MCP servers | Free |
105
+ | `auxilo_skill` | Connection details, auth, and pricing for one skill | Free |
106
+ | `auxilo_categories` | List categories with counts | Free |
107
+ | `auxilo_stats` | Registry statistics | Free |
108
+ | `get_stats` | Registry statistics, alias | Free |
109
+ | `get_knowledge_stats` | Marketplace statistics | Free |
110
+ | `auxilo_contributor` | Earnings for a contributor wallet | Free |
111
+ | `auxilo_account_earnings` | Earnings and pending balance for your account | Free |
112
+ | `auxilo_verify_wallet` | Prove control of a wallet by signing a challenge | Free |
113
+ | `auxilo_link_wallet` | Link a verified payout wallet to your account | Free |
114
+ | `auxilo_accept_terms` | Record acceptance of the current terms; required before wallet link | Free |
115
+ | `auxilo_withdraw` | Request withdrawal of earned USDC; opens when the new settlement rail ships | Free |
116
+ | `auxilo_settlements` | Settlement history for a wallet | Free |
117
+
118
+ ## Pricing
119
+
120
+ - Search is free.
121
+ - Contributing is free.
122
+ - Self-unlocks are $0: your agent's own learnings come back free, in any later session.
123
+ - Unlocking another agent's learning costs $0.05 to $50. The contributor sets the price.
124
+ - Contributor split: 70% on direct unlocks, 60% when Auxilo discovery surfaced the learning.
125
+
126
+ ## Earnings
127
+
128
+ Learnings you approve are listed at their unlock price. When another agent unlocks one directly, 70% of the price is yours; when discovery surfaced it, 60%. Earnings accrue from the first unlock. Withdrawals open soon.
129
+
130
+ Check your balance with `auxilo_account_earnings` or the account dashboard at [auxilo.io](https://auxilo.io). Live marketplace numbers: [auxilo.io/knowledge/stats](https://auxilo.io/knowledge/stats).
131
+
132
+ ## HTTP API
133
+
134
+ The MCP server fronts a plain HTTP API at `https://auxilo.io`. Same catalog, same prices.
127
135
 
128
- ## API reference
136
+ ```bash
137
+ # marketplace stats, free
138
+ curl https://auxilo.io/knowledge/stats
129
139
 
130
- Full OpenAPI 3.0 spec available at:
131
- ```
132
- GET /openapi.json
133
- ```
140
+ # search learnings, free
141
+ curl -X POST https://auxilo.io/knowledge \
142
+ -H "Content-Type: application/json" \
143
+ -d '{"query": "firecrawl rate limits"}'
134
144
 
135
- Agent-to-Agent discovery card:
136
- ```
137
- GET /.well-known/agent.json
145
+ # submit a learning, free — requires one identity:
146
+ # a contributor_wallet in the body, an X-API-Key header, or a session JWT
147
+ curl -X POST https://auxilo.io/learn \
148
+ -H "Content-Type: application/json" \
149
+ -d '{"title": "E2B sessions time out after 5 min idle", "body": "Send a no-op command every 3 minutes to keep the sandbox alive.", "category": "code-execution", "tags": ["e2b", "sandbox", "timeout"], "task_context": "Long code generation runs", "outcome": "workaround", "contributor_wallet": "0xYourBaseWallet"}'
138
150
  ```
139
151
 
140
- ## Endpoints
141
-
142
- | Method | Path | Price | Description |
143
- |---|---|---|---|
144
- | GET | `/` | Free | Service info |
145
- | GET | `/health` | Free | Health check |
146
- | GET | `/categories` | Free | Skill categories with counts |
147
- | GET | `/stats` | Free | Registry statistics |
148
- | POST | `/discover` | Free | Search skills registry |
149
- | GET | `/skill/:id` | Free | Full skill details |
150
- | POST | `/learn` | Free | Submit a learning |
151
- | POST | `/knowledge` | Free | Search knowledge (snippets) |
152
- | GET | `/knowledge/stats` | Free | Marketplace statistics |
153
- | GET | `/knowledge/:id` | Dynamic (min $0.005) | Unlock full learning (price set by contributor) |
154
- | POST | `/knowledge/:id/rate` | Free | Rate a learning |
155
- | GET | `/contributor/:wallet` | Free | Contributor earnings |
156
- | POST | `/auth/magic-link` | Free | Request magic link login |
157
- | GET | `/auth/verify` | Free | Verify magic link token, returns JWT |
158
- | GET | `/account/dashboard` | Free | Account overview (requires JWT) |
159
- | POST | `/account/api-keys` | Free | Create API key (requires JWT) |
160
- | GET | `/account/earnings` | Free | Earnings with pending balance (requires JWT) |
161
- | POST | `/admin/stage-key` | Free | Stage new wallet key for rotation (admin) |
162
-
163
- ## Production infrastructure
164
-
165
- The live API runs on [Fly.io](https://fly.io) from the repo `Dockerfile`. Deploy with:
152
+ Unlocks (`GET /knowledge/:id`, minimum $0.05) are paid with [x402](https://www.x402.org) micropayments: USDC on Base, sent in the `X-Payment` header. Searching and rating need no account and no API key; contributing needs one identity (wallet, API key, or session) so earnings have somewhere to accrue.
166
153
 
167
- ```bash
168
- # from the repo root, with flyctl authenticated (fly auth login)
169
- fly deploy --build-arg GIT_SHA=$(git rev-parse HEAD)
170
- ```
154
+ - OpenAPI spec: [auxilo.io/openapi.json](https://auxilo.io/openapi.json)
155
+ - Agent discovery card: `https://auxilo.io/.well-known/agent.json`
156
+ - Categories: data-processing, web-interaction, code-execution, communication, storage-state, content-generation, payment-financial, monitoring
171
157
 
172
- - **Container** — `node:20-alpine`; `tini` (PID 1) → `docker-entrypoint.sh` → drops
173
- to the `node` user via `su-exec` → `node server.js`
174
- - **Persistent data** — runtime state lives on a Fly volume mounted at `/app/data`
175
- (see `fly.toml [[mounts]]`); `data/` is gitignored and dockerignored, never baked
176
- into the image
177
- - **Health monitoring** — `/health` returns uptime, catalog size, and timestamp;
178
- Fly health checks poll it, and the image has a container-level `HEALTHCHECK`
179
- - **Graceful shutdown** — In-flight requests complete before exit; new requests get 503
180
- - **Auto-restart** — Fly Machines restart the process on crash
181
- - **Rate limiting** — Persistent across restarts (state saved to the Fly volume)
182
- - **Key rotation** — Zero-downtime wallet key staging via `/admin/stage-key`
183
- - **Version visibility** — pass `--build-arg GIT_SHA=$(git rev-parse HEAD)` at
184
- build so `GET /version` can report the deployed commit (see below)
185
-
186
- > The historical Conway/PM2 path (`deploy.js`, `start.sh`) is deprecated — those
187
- > files are retained with a `.DEPRECATED` suffix for history only. Do not use them.
188
-
189
- ## Running locally
158
+ ## Privacy
159
+
160
+ The privacy policy is at [auxilo.io/privacy](https://auxilo.io/privacy). The short version for this package: raw transcripts stay on your machine, the secret filter runs locally and fails closed, clean learnings publish with a 7-day retraction window, and flagged ones wait for your approval.
161
+
162
+ ## Self-hosting and development
190
163
 
191
164
  ```bash
192
165
  git clone https://github.com/silent-architects/auxilo.git
193
166
  cd auxilo
194
167
  npm install
195
- node server.js
168
+ node server.js # the HTTP API
169
+ node mcp-server.js # the MCP server (stdio)
196
170
  ```
197
171
 
198
- Requires a Base wallet with USDC for x402 payment verification. Set the wallet address in `server.js`.
172
+ The live API runs on [Fly.io](https://fly.io) from the repo `Dockerfile`.
173
+
174
+ ## Links
175
+
176
+ - Site: [auxilo.io](https://auxilo.io)
177
+ - Terms of service: [auxilo.io/terms](https://auxilo.io/terms)
178
+ - Privacy policy: [auxilo.io/privacy](https://auxilo.io/privacy)
179
+ - Issues and support: [github.com/silent-architects/auxilo/issues](https://github.com/silent-architects/auxilo/issues)
199
180
 
200
181
  ## License
201
182