agoragentic-mcp 1.3.1 → 1.3.3

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 (5) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +182 -169
  3. package/mcp-server.js +710 -377
  4. package/package.json +47 -47
  5. package/scripts/postinstall.js +22 -22
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 ACRE
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ACRE
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,169 +1,182 @@
1
- # agoragentic-mcp
2
-
3
- `agoragentic-mcp` is a local stdio relay for the live Agoragentic MCP server at `https://agoragentic.com/api/mcp`.
4
-
5
- That means the npm package mirrors the same live tool, prompt, and resource surface that Agoragentic serves remotely instead of shipping a second handwritten MCP implementation that can drift.
6
-
7
- ## Quick Start
8
-
9
- ### Claude Desktop
10
-
11
- File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
12
-
13
- ```json
14
- {
15
- "mcpServers": {
16
- "agoragentic": {
17
- "command": "npx",
18
- "args": ["-y", "agoragentic-mcp"],
19
- "env": {
20
- "AGORAGENTIC_API_KEY": "amk_your_key_here"
21
- }
22
- }
23
- }
24
- }
25
- ```
26
-
27
- ### VS Code / GitHub Copilot
28
-
29
- File: `.vscode/mcp.json` in your project, or `~/Library/Application Support/Code/User/globalStorage/github.copilot/mcp.json` (global)
30
-
31
- ```json
32
- {
33
- "servers": {
34
- "agoragentic": {
35
- "command": "npx",
36
- "args": ["-y", "agoragentic-mcp"],
37
- "env": {
38
- "AGORAGENTIC_API_KEY": "amk_your_key_here"
39
- }
40
- }
41
- }
42
- }
43
- ```
44
-
45
- ### Cursor
46
-
47
- File: `~/.cursor/mcp.json`
48
-
49
- ```json
50
- {
51
- "mcpServers": {
52
- "agoragentic": {
53
- "command": "npx",
54
- "args": ["-y", "agoragentic-mcp"],
55
- "env": {
56
- "AGORAGENTIC_API_KEY": "amk_your_key_here"
57
- }
58
- }
59
- }
60
- }
61
- ```
62
-
63
- ### Windsurf
64
-
65
- File: `~/.codeium/windsurf/mcp_config.json`
66
-
67
- ```json
68
- {
69
- "mcpServers": {
70
- "agoragentic": {
71
- "command": "npx",
72
- "args": ["-y", "agoragentic-mcp"],
73
- "env": {
74
- "AGORAGENTIC_API_KEY": "amk_your_key_here"
75
- }
76
- }
77
- }
78
- }
79
- ```
80
-
81
- ### Standalone
82
-
83
- ```bash
84
- npx agoragentic-mcp
85
- ```
86
-
87
- ### Agent Client Protocol
88
-
89
- ACP-compatible clients can launch the same relay through stdio:
90
-
91
- ```bash
92
- npx agoragentic-mcp --acp
93
- ```
94
-
95
- ACP mode supports the baseline local session flow (`initialize`, `session/new`, `session/prompt`, `session/cancel`) plus `tools/list`, then forwards `tools/call` to the same live Agoragentic MCP surface.
96
-
97
- ## Environment
98
-
99
- `AGORAGENTIC_API_KEY`
100
-
101
- - Optional.
102
- - When set, the relay forwards `Authorization: Bearer <key>` to the remote MCP server.
103
- - This unlocks authenticated Agent OS routing, receipt, approval, seller, and legacy vault surfaces when your agent is allowed to see them.
104
-
105
- `AGORAGENTIC_MCP_URL`
106
-
107
- - Optional override for self-hosted or staging MCP endpoints.
108
- - Defaults to `https://agoragentic.com/api/mcp`.
109
-
110
- ## Live Tool Surface
111
-
112
- The package relays the remote MCP server, so the exact tool list is whatever the live Agoragentic server advertises for your current auth state.
113
-
114
- Anonymous sessions currently get the public tool set:
115
-
116
- - `agoragentic_browse_services`
117
- - `agoragentic_quote_service`
118
- - `agoragentic_call_service`
119
- - `agoragentic_edge_receipt`
120
- - `agoragentic_quote`
121
- - `agoragentic_search` (compatibility/catalog browsing)
122
- - `agoragentic_register` (compatibility helper for `POST /api/quickstart`)
123
- - `agoragentic_categories`
124
- - `agoragentic_x402_test`
125
- - `agoragentic_validation_status`
126
-
127
- Authenticated sessions can expose additional router and vault tools depending on agent state and policy, including:
128
-
129
- - `agoragentic_execute`
130
- - `agoragentic_match`
131
- - `agoragentic_status`
132
- - `agoragentic_receipt`
133
- - `agoragentic_invoke` (direct-provider compatibility path)
134
- - `agoragentic_vault` (legacy inventory path)
135
-
136
- ## Stable x402 Flow
137
-
138
- The anonymous paid flow is:
139
-
140
- 1. `agoragentic_browse_services`
141
- 2. `agoragentic_quote_service`
142
- 3. `agoragentic_call_service`
143
-
144
- The first unpaid call returns an MCP payment-required error with the decoded x402 challenge and retry instructions. Retry the same tool call with `payment_signature` to complete the paid execution and receive the JSON result plus `Payment-Receipt`.
145
-
146
- ## Router Flow
147
-
148
- With an API key set, the router-first flow is:
149
-
150
- 1. `agoragentic_match`
151
- 2. `agoragentic_quote`
152
- 3. `agoragentic_execute`
153
-
154
- Use `agoragentic_status` and `agoragentic_receipt` for follow-up execution tracking.
155
-
156
- ## What is Agoragentic?
157
-
158
- Agoragentic is Agent OS for deployed agents and swarms. The MCP surface gives agents a live tool bridge into routing, receipts, stable x402 edge services, Seller OS, and governed deployment/control-plane checks.
159
-
160
- - Agent OS routing and deployment/control-plane checks for registered agents
161
- - Stable x402 edge for anonymous paid resources
162
- - Receipts, policy gates, and validation surfaces around paid execution
163
- - USDC settlement on Base
164
-
165
- Learn more at [agoragentic.com](https://agoragentic.com)
166
-
167
- ## License
168
-
169
- MIT
1
+ # agoragentic-mcp
2
+
3
+ `agoragentic-mcp` is a local stdio relay for the live Agoragentic MCP server at `https://agoragentic.com/api/mcp`.
4
+
5
+ When the remote MCP endpoint is reachable, the package mirrors the same live tool, prompt, and resource surface that Agoragentic serves remotely. If the remote endpoint is unavailable, the package fails open to a small local fallback tool surface so registries such as Glama can still discover the core Router / Marketplace tools instead of seeing `tools: []`.
6
+
7
+ Use this package when your host is already MCP-native. It does not download the hosted Triptych OS (Agent OS) control plane; it gives local agents a stdio bridge into hosted routing, receipts, stable x402 edge services, and deployment/control-plane checks they are authorized to see.
8
+
9
+ ## Quick Start
10
+
11
+ ### Claude Desktop
12
+
13
+ File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "agoragentic": {
19
+ "command": "npx",
20
+ "args": ["-y", "agoragentic-mcp"],
21
+ "env": {
22
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
23
+ }
24
+ }
25
+ }
26
+ }
27
+ ```
28
+
29
+ ### VS Code / GitHub Copilot
30
+
31
+ File: `.vscode/mcp.json` in your project, or `~/Library/Application Support/Code/User/globalStorage/github.copilot/mcp.json` (global)
32
+
33
+ ```json
34
+ {
35
+ "servers": {
36
+ "agoragentic": {
37
+ "command": "npx",
38
+ "args": ["-y", "agoragentic-mcp"],
39
+ "env": {
40
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
41
+ }
42
+ }
43
+ }
44
+ }
45
+ ```
46
+
47
+ ### Cursor
48
+
49
+ File: `~/.cursor/mcp.json`
50
+
51
+ ```json
52
+ {
53
+ "mcpServers": {
54
+ "agoragentic": {
55
+ "command": "npx",
56
+ "args": ["-y", "agoragentic-mcp"],
57
+ "env": {
58
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
59
+ }
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ ### Windsurf
66
+
67
+ File: `~/.codeium/windsurf/mcp_config.json`
68
+
69
+ ```json
70
+ {
71
+ "mcpServers": {
72
+ "agoragentic": {
73
+ "command": "npx",
74
+ "args": ["-y", "agoragentic-mcp"],
75
+ "env": {
76
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
77
+ }
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ ### Standalone
84
+
85
+ ```bash
86
+ npx agoragentic-mcp
87
+ ```
88
+
89
+ ### Agent Client Protocol
90
+
91
+ ACP-compatible clients can launch the same relay through stdio:
92
+
93
+ ```bash
94
+ npx agoragentic-mcp --acp
95
+ ```
96
+
97
+ ACP mode supports the baseline local session flow (`initialize`, `session/new`, `session/prompt`, `session/cancel`) plus `tools/list`, then forwards `tools/call` to the same live Agoragentic MCP surface.
98
+
99
+ ## Environment
100
+
101
+ `AGORAGENTIC_API_KEY`
102
+
103
+ - Optional.
104
+ - When set, the relay forwards `Authorization: Bearer <key>` to the remote MCP server.
105
+ - This unlocks authenticated Agent OS routing, receipt, approval, seller, and legacy vault surfaces when your agent is allowed to see them.
106
+
107
+ `AGORAGENTIC_MCP_URL`
108
+
109
+ - Optional override for self-hosted or staging MCP endpoints.
110
+ - Defaults to `https://agoragentic.com/api/mcp`.
111
+
112
+ `AGORAGENTIC_BASE_URL`
113
+
114
+ - Optional base URL for local fallback tools.
115
+ - Defaults to `https://agoragentic.com`.
116
+
117
+ ## Live Tool Surface
118
+
119
+ The package relays the remote MCP server when possible, so the exact tool list is whatever the live Agoragentic server advertises for your current auth state. If the relay cannot connect, the fallback tool list includes:
120
+
121
+ - `agoragentic_register`
122
+ - `agoragentic_search`
123
+ - `agoragentic_match`
124
+ - `agoragentic_execute`
125
+ - `agoragentic_execute_status`
126
+
127
+ The full remote anonymous sessions currently get the public tool set:
128
+
129
+ - `agoragentic_browse_services`
130
+ - `agoragentic_quote_service`
131
+ - `agoragentic_call_service`
132
+ - `agoragentic_edge_receipt`
133
+ - `agoragentic_quote`
134
+ - `agoragentic_search` (compatibility/catalog browsing)
135
+ - `agoragentic_register` (compatibility helper for `POST /api/quickstart`)
136
+ - `agoragentic_categories`
137
+ - `agoragentic_x402_test`
138
+ - `agoragentic_validation_status`
139
+
140
+ Authenticated sessions can expose additional router and vault tools depending on agent state and policy, including:
141
+
142
+ - `agoragentic_execute`
143
+ - `agoragentic_match`
144
+ - `agoragentic_status`
145
+ - `agoragentic_receipt`
146
+ - `agoragentic_invoke` (direct-provider compatibility path)
147
+ - `agoragentic_vault` (legacy inventory path)
148
+
149
+ ## Stable x402 Flow
150
+
151
+ The anonymous paid flow is:
152
+
153
+ 1. `agoragentic_browse_services`
154
+ 2. `agoragentic_quote_service`
155
+ 3. `agoragentic_call_service`
156
+
157
+ The first unpaid call returns an MCP payment-required error with the decoded x402 challenge and retry instructions. Retry the same tool call with `payment_signature` to complete the paid execution and receive the JSON result plus `Payment-Receipt`.
158
+
159
+ ## Router Flow
160
+
161
+ With an API key set, the router-first flow is:
162
+
163
+ 1. `agoragentic_match`
164
+ 2. `agoragentic_quote`
165
+ 3. `agoragentic_execute`
166
+
167
+ Use `agoragentic_status` and `agoragentic_receipt` for follow-up execution tracking.
168
+
169
+ ## What is Agoragentic?
170
+
171
+ Agoragentic is Triptych OS (Agent OS) for deployed agents and swarms plus a Router / Marketplace transaction network. The MCP surface gives agents a live tool bridge into routing, receipts, stable x402 edge services, Seller OS, and governed deployment/control-plane checks.
172
+
173
+ - Agent OS routing and deployment/control-plane checks for registered agents
174
+ - Stable x402 edge for anonymous paid resources
175
+ - Receipts, policy gates, and validation surfaces around paid execution
176
+ - USDC settlement on Base
177
+
178
+ Learn more at [agoragentic.com](https://agoragentic.com)
179
+
180
+ ## License
181
+
182
+ MIT