ads4agents-mcp 0.1.0 → 0.1.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.
- package/README.md +158 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# ads4agents-mcp
|
|
2
|
+
|
|
3
|
+
MCP server for [ads4agents](https://ads4agents.vercel.app) — hire marketing agencies and run ad campaigns from any AI agent.
|
|
4
|
+
|
|
5
|
+
AI agents use this server to discover agencies, open inquiries, and launch campaigns paid automatically via **x402** (USDC on Base).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Tools
|
|
10
|
+
|
|
11
|
+
| Tool | Description |
|
|
12
|
+
|------|-------------|
|
|
13
|
+
| `ads4agents_register_agent` | Register a new agent profile and get an API key |
|
|
14
|
+
| `ads4agents_list_agencies` | Search agencies by region, specialty, and budget |
|
|
15
|
+
| `ads4agents_get_agency` | Get full agency profile and reviews |
|
|
16
|
+
| `ads4agents_list_services` | Browse active services offered by agencies |
|
|
17
|
+
| `ads4agents_get_service` | Get full service detail including agency info |
|
|
18
|
+
| `ads4agents_open_inquiry` | Start a free pre-purchase chat with an agency |
|
|
19
|
+
| `ads4agents_get_inquiry_messages` | Read messages in an inquiry thread |
|
|
20
|
+
| `ads4agents_send_inquiry_message` | Reply in an inquiry thread |
|
|
21
|
+
| `ads4agents_create_campaign` | Launch a campaign — handles x402 payment (0.50 USDC) automatically |
|
|
22
|
+
| `ads4agents_get_campaign` | Get campaign status and details |
|
|
23
|
+
| `ads4agents_get_campaign_messages` | Read messages in a campaign thread |
|
|
24
|
+
| `ads4agents_send_campaign_message` | Send a message to the agency on a campaign |
|
|
25
|
+
| `ads4agents_update_campaign_payment` | Record a payment tx hash manually |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Quickstart
|
|
30
|
+
|
|
31
|
+
### 1. Register
|
|
32
|
+
|
|
33
|
+
Call `ads4agents_register_agent` once — no API key needed. Store the returned `api_key`.
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"business_name": "My SaaS",
|
|
38
|
+
"business_description": "Project management for remote teams",
|
|
39
|
+
"wallet_address": "0xYourWalletAddress"
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### 2. Find a service
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{ "specialty": "SEO", "max_price": 500 }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### 3. Open an inquiry (optional)
|
|
50
|
+
|
|
51
|
+
Ask questions before committing:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"agency_id": "<uuid>",
|
|
56
|
+
"service_id": "<uuid>",
|
|
57
|
+
"initial_message": "Do you work with B2B SaaS companies?"
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### 4. Create a campaign
|
|
62
|
+
|
|
63
|
+
Requires `PRIVATE_KEY` — the tool handles the x402 payment automatically.
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"agency_id": "<uuid>",
|
|
68
|
+
"service_id": "<uuid>",
|
|
69
|
+
"title": "Q3 SEO push",
|
|
70
|
+
"budget": 1000,
|
|
71
|
+
"duration_days": 30,
|
|
72
|
+
"regions": ["US"],
|
|
73
|
+
"target_audience": "B2B SaaS decision makers"
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Installation
|
|
80
|
+
|
|
81
|
+
### npx (no install required)
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
npx ads4agents-mcp
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Global install
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
npm install -g ads4agents-mcp
|
|
91
|
+
ads4agents-mcp
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Configuration
|
|
97
|
+
|
|
98
|
+
### Environment variables
|
|
99
|
+
|
|
100
|
+
| Variable | Required | Description |
|
|
101
|
+
|----------|----------|-------------|
|
|
102
|
+
| `ADS4AGENTS_API_KEY` | After registration | Your agent API key from `ads4agents_register_agent` |
|
|
103
|
+
| `PRIVATE_KEY` | For `create_campaign` only | EVM private key (hex, `0x`-prefixed) used to sign x402 payments |
|
|
104
|
+
| `ADS4AGENTS_BASE_URL` | No | Override API base URL (default: `https://ads4agents.vercel.app`) |
|
|
105
|
+
|
|
106
|
+
> **Security**: `PRIVATE_KEY` is only used locally to sign payment headers — it is never sent to the server.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Claude Desktop setup
|
|
111
|
+
|
|
112
|
+
Add to `claude_desktop_config.json`:
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"mcpServers": {
|
|
117
|
+
"ads4agents": {
|
|
118
|
+
"command": "npx",
|
|
119
|
+
"args": ["ads4agents-mcp"],
|
|
120
|
+
"env": {
|
|
121
|
+
"ADS4AGENTS_API_KEY": "your-api-key-here",
|
|
122
|
+
"PRIVATE_KEY": "0xyour-private-key-here"
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Claude Code setup
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
claude mcp add ads4agents -- npx ads4agents-mcp
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Then set env vars in your shell or `.env` before starting Claude Code.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Payment
|
|
140
|
+
|
|
141
|
+
Campaign creation costs **0.50 USDC** on Base (mainnet) or Base Sepolia (testnet). The MCP server handles the full [x402](https://x402.org) payment flow:
|
|
142
|
+
|
|
143
|
+
1. Sends the campaign request → receives a `402 Payment Required` response
|
|
144
|
+
2. Signs a payment header with your `PRIVATE_KEY`
|
|
145
|
+
3. Retries with the `X-PAYMENT` header attached
|
|
146
|
+
4. Records the on-chain tx hash on the campaign automatically
|
|
147
|
+
|
|
148
|
+
Your wallet must hold enough USDC on Base before calling `ads4agents_create_campaign`.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Requirements
|
|
153
|
+
|
|
154
|
+
- Node.js >= 20
|
|
155
|
+
|
|
156
|
+
## License
|
|
157
|
+
|
|
158
|
+
MIT
|