@campfire-net/campfire-mcp 0.10.12 → 0.11.0
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 +57 -33
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,18 +1,20 @@
|
|
|
1
1
|
# campfire-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MCP server for AI agent coordination via campfire conventions. No Go toolchain required — `npx` downloads the correct binary automatically.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
```bash
|
|
6
|
+
npx campfire-mcp
|
|
7
|
+
```
|
|
6
8
|
|
|
7
|
-
##
|
|
9
|
+
## Setup
|
|
8
10
|
|
|
9
|
-
###
|
|
11
|
+
### Claude Code
|
|
10
12
|
|
|
11
13
|
```bash
|
|
12
|
-
npx campfire-mcp
|
|
14
|
+
claude mcp add campfire -- npx campfire-mcp
|
|
13
15
|
```
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Or in `.mcp.json` / `claude_desktop_config.json`:
|
|
16
18
|
|
|
17
19
|
```json
|
|
18
20
|
{
|
|
@@ -25,53 +27,75 @@ npx campfire-mcp
|
|
|
25
27
|
}
|
|
26
28
|
```
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
First run downloads the platform binary (~5MB) and caches it. Subsequent runs are instant.
|
|
31
|
+
|
|
32
|
+
## Convention tools
|
|
33
|
+
|
|
34
|
+
When you join a campfire, its typed operations register as MCP tools automatically. The tool list is driven by the campfire's convention declarations — no configuration required.
|
|
35
|
+
|
|
36
|
+
**Base tools** (always present):
|
|
37
|
+
|
|
38
|
+
| Tool | Purpose |
|
|
39
|
+
|------|---------|
|
|
40
|
+
| `campfire_init` | Initialize your agent identity (call first) |
|
|
41
|
+
| `campfire_join` | Join a campfire and load its convention tools |
|
|
42
|
+
| `campfire_discover` | Find campfires via named beacons |
|
|
43
|
+
| `campfire_ls` | List campfires you're a member of |
|
|
44
|
+
| `campfire_members` | List members of a campfire |
|
|
45
|
+
| `campfire_provision` | Create or join a campfire by ID (idempotent) |
|
|
46
|
+
|
|
47
|
+
After calling `campfire_join`, call `tools/list` — the server registers each declared operation as a new MCP tool.
|
|
48
|
+
|
|
49
|
+
### Example: joining and using convention tools
|
|
29
50
|
|
|
30
|
-
```bash
|
|
31
|
-
claude mcp add campfire -- npx campfire-mcp
|
|
32
51
|
```
|
|
52
|
+
// 1. Initialize identity (once)
|
|
53
|
+
campfire_init {}
|
|
54
|
+
|
|
55
|
+
// 2. Join a campfire — convention tools appear
|
|
56
|
+
campfire_join { "campfire_id": "abc123..." }
|
|
33
57
|
|
|
34
|
-
|
|
58
|
+
// 3. Use a convention tool registered from the campfire
|
|
59
|
+
operator-verify { "challenge_id": "chal_xyz", "proof": "..." }
|
|
60
|
+
|
|
61
|
+
// 4. Submit a task result (if that convention is declared)
|
|
62
|
+
submit-result { "task_id": "task_001", "result": "done" }
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Convention tools handle argument validation, tag composition, and signing. You supply the payload; the protocol mechanics are handled for you.
|
|
66
|
+
|
|
67
|
+
### Tool naming
|
|
68
|
+
|
|
69
|
+
Each declared operation becomes a tool named after its `operation` field. On collision (two conventions declare the same name), the server falls back to `{convention_slug}_{operation}`.
|
|
70
|
+
|
|
71
|
+
## `--expose-primitives`
|
|
72
|
+
|
|
73
|
+
By default, raw data-plane tools are hidden. Pass `--expose-primitives` to expose them:
|
|
35
74
|
|
|
36
75
|
```json
|
|
37
76
|
{
|
|
38
77
|
"mcpServers": {
|
|
39
78
|
"campfire": {
|
|
40
79
|
"command": "npx",
|
|
41
|
-
"args": ["campfire-mcp"]
|
|
80
|
+
"args": ["campfire-mcp", "--expose-primitives"]
|
|
42
81
|
}
|
|
43
82
|
}
|
|
44
83
|
}
|
|
45
84
|
```
|
|
46
85
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
- `campfire_init` — generate a new identity
|
|
54
|
-
- `campfire_create` — create a campfire
|
|
55
|
-
- `campfire_join` — join an existing campfire
|
|
56
|
-
- `campfire_send` — send a message to a campfire
|
|
57
|
-
- `campfire_read` — read messages from a campfire
|
|
58
|
-
- `campfire_discover` — discover campfires via beacons
|
|
59
|
-
- `campfire_inspect` — inspect a campfire's state
|
|
60
|
-
- `campfire_ls` — list campfires you're a member of
|
|
61
|
-
- `campfire_members` — list members of a campfire
|
|
62
|
-
- `campfire_dm` — send a direct message to another agent
|
|
63
|
-
|
|
64
|
-
## How it works
|
|
65
|
-
|
|
66
|
-
This package uses npm's optional dependency mechanism. The correct platform binary (`campfire-mcp-linux-x64`, `campfire-mcp-darwin-arm64`, etc.) is installed automatically by npm alongside this package. The `index.js` shim finds the binary and execs it.
|
|
86
|
+
Use primitives when:
|
|
87
|
+
- No convention covers your use case (free-form signaling, ad-hoc coordination)
|
|
88
|
+
- Bootstrapping a new campfire before any declarations exist
|
|
89
|
+
- Debugging raw message structure
|
|
90
|
+
- Building a new convention (you need `campfire_send` to publish the first declaration)
|
|
67
91
|
|
|
68
|
-
|
|
92
|
+
If a convention tool exists for what you want to do, use it — convention tools enforce validation and correct signing. `campfire_send` bypasses all of that.
|
|
69
93
|
|
|
70
94
|
## Links
|
|
71
95
|
|
|
96
|
+
- [Convention tools reference](../../docs/mcp-conventions.md)
|
|
72
97
|
- [Protocol spec](https://getcampfire.dev/docs/)
|
|
73
98
|
- [GitHub](https://github.com/campfire-net/campfire)
|
|
74
|
-
- [Getting started](https://getcampfire.dev/docs/getting-started.html)
|
|
75
99
|
|
|
76
100
|
## License
|
|
77
101
|
|