@cyanheads/cyanheads-mcp-server 0.1.3 → 0.1.5
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/AGENTS.md +1 -1
- package/CLAUDE.md +1 -1
- package/README.md +199 -75
- package/changelog/0.1.x/0.1.4.md +22 -0
- package/changelog/0.1.x/0.1.5.md +31 -0
- package/dist/mcp-server/tools/definitions/describe.tool.d.ts +8 -4
- package/dist/mcp-server/tools/definitions/describe.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/describe.tool.js +3 -3
- package/dist/mcp-server/tools/definitions/describe.tool.js.map +1 -1
- package/dist/services/catalog/embeddings-runtime.d.ts.map +1 -1
- package/dist/services/catalog/embeddings-runtime.js +13 -1
- package/dist/services/catalog/embeddings-runtime.js.map +1 -1
- package/dist/services/catalog/snippets.d.ts +9 -1
- package/dist/services/catalog/snippets.d.ts.map +1 -1
- package/dist/services/catalog/snippets.js +67 -20
- package/dist/services/catalog/snippets.js.map +1 -1
- package/dist/services/catalog/types.d.ts +8 -6
- package/dist/services/catalog/types.d.ts.map +1 -1
- package/manifest.json +48 -0
- package/package.json +5 -1
- package/server.json +9 -3
package/AGENTS.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** cyanheads-mcp-server
|
|
4
|
-
**Version:** 0.1.
|
|
4
|
+
**Version:** 0.1.5
|
|
5
5
|
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.11`
|
|
6
6
|
**Engines:** Bun ≥1.3.0, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
|
package/CLAUDE.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** cyanheads-mcp-server
|
|
4
|
-
**Version:** 0.1.
|
|
4
|
+
**Version:** 0.1.5
|
|
5
5
|
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.11`
|
|
6
6
|
**Engines:** Bun ≥1.3.0, Node ≥24.0.0
|
|
7
7
|
**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
|
package/README.md
CHANGED
|
@@ -1,143 +1,267 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>@cyanheads/cyanheads-mcp-server</h1>
|
|
3
|
+
<p><b>Discover MCP servers via semantic search. One endpoint, 40+ hosted servers, per-client install snippets. STDIO or Streamable HTTP.</b>
|
|
4
|
+
<div>2 Tools • 0 Resources • 0 Prompts</div>
|
|
5
|
+
</p>
|
|
6
|
+
</div>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
<div align="center">
|
|
4
9
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
10
|
+
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/cyanheads-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/cyanheads-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
<div align="center">
|
|
15
|
+
|
|
16
|
+
[](https://github.com/cyanheads/cyanheads-mcp-server/releases/latest/download/cyanheads-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=cyanheads-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY3lhbmhlYWRzLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22cyanheads-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/cyanheads-mcp-server%22%5D%7D)
|
|
17
|
+
|
|
18
|
+
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
|
|
8
19
|
|
|
9
|
-
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
<div align="center">
|
|
23
|
+
|
|
24
|
+
**Public Hosted Server:** [https://cyanheads.caseyjhand.com/mcp](https://cyanheads.caseyjhand.com/mcp)
|
|
25
|
+
|
|
26
|
+
</div>
|
|
10
27
|
|
|
11
28
|
---
|
|
12
29
|
|
|
13
|
-
##
|
|
30
|
+
## Tools
|
|
31
|
+
|
|
32
|
+
Two tools, semantic ranking, hosted catalog. The catalog itself lives at [`caseyjhand.com/fleet.json`](https://caseyjhand.com/fleet.json) — a single JSON file with baked embeddings, regenerated when servers are added or updated. This server polls it hourly and serves search out of an in-memory vector index.
|
|
33
|
+
|
|
34
|
+
| Tool | Description |
|
|
35
|
+
|:---|:---|
|
|
36
|
+
| `cyanheads_search` | Search fleet tools and servers by natural-language query. Returns ranked matches with brief summaries and the owning server. |
|
|
37
|
+
| `cyanheads_describe` | Return the connection URL and per-client install snippets for a named tool or server. |
|
|
38
|
+
|
|
39
|
+
### `cyanheads_search`
|
|
40
|
+
|
|
41
|
+
Semantic search across the fleet. Embeds the query with [Snowflake Arctic Embed M v1.5](https://huggingface.co/Snowflake/snowflake-arctic-embed-m-v1.5) (Matryoshka-truncated to 256 dimensions) and computes cosine similarity against the catalog's pre-computed document vectors.
|
|
42
|
+
|
|
43
|
+
- `scope: "tools"` (default) returns individual tool matches; `scope: "servers"` returns server-level matches
|
|
44
|
+
- `category` filter narrows to one of `research`, `government`, `public-data`, `utility`
|
|
45
|
+
- Configurable `limit` (1-20, default 5) and a server-side `SIMILARITY_FLOOR` threshold drop low-confidence hits
|
|
46
|
+
- Returns `score` (cosine similarity in [0, 1]) on every result for trust calibration
|
|
47
|
+
- `totalMatched` reports the count above the floor before the limit was applied
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
### `cyanheads_describe`
|
|
52
|
+
|
|
53
|
+
Resolve a name to its install instructions. Accepts either a tool name (snake_case, e.g. `earthquake_search`) or a server name (kebab-case, e.g. `earthquake-mcp-server`) — auto-detected from the format, or pinned via the `kind` parameter.
|
|
54
|
+
|
|
55
|
+
- For tools: returns the description and the owning server name
|
|
56
|
+
- For servers: returns description, version, npm package, GitHub URL, hosted endpoint URL, tool count, and per-client install snippets
|
|
57
|
+
- `client` filter narrows snippets to one of `claude-desktop`, `claude-code`, `cursor`, `cline`; omit to return all four
|
|
58
|
+
- Discriminated output on `kind` — callers branch on data, not string parsing
|
|
59
|
+
|
|
60
|
+
## Features
|
|
61
|
+
|
|
62
|
+
Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
|
|
14
63
|
|
|
15
|
-
|
|
64
|
+
- Declarative tool definitions — single file per tool, framework handles registration and validation
|
|
65
|
+
- Unified error handling with typed error contracts and recovery hints
|
|
66
|
+
- Pluggable auth (`none`, `jwt`, `oauth`)
|
|
67
|
+
- Structured logging with optional OpenTelemetry tracing
|
|
68
|
+
- Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase
|
|
16
69
|
|
|
17
|
-
|
|
70
|
+
Fleet-specific:
|
|
71
|
+
|
|
72
|
+
- Hourly background catalog refresh with atomic swap on `generatedAt` change — no restart needed when the fleet updates
|
|
73
|
+
- L2-normalized 256-dim Matryoshka-truncated vectors keep memory under 100KB for a 40-server fleet
|
|
74
|
+
- Per-client install snippet generation (Claude Desktop, Claude Code, Cursor, Cline) at describe-time, not catalog-generation time — snippets stay in sync with the deployed endpoint
|
|
75
|
+
- Discriminated `result.kind` and typed `installSnippets[].client` enums — agents can branch reliably
|
|
76
|
+
|
|
77
|
+
## What's in the fleet
|
|
78
|
+
|
|
79
|
+
40+ MCP servers spanning four categories. Each is open source and individually addressable — `cyanheads_describe` returns its direct connection URL alongside the install snippet.
|
|
80
|
+
|
|
81
|
+
| Category | Examples |
|
|
82
|
+
|:--|:--|
|
|
83
|
+
| **Research** | arXiv, bioRxiv, ORCID, Crossref, Wikipedia, Wikidata, OpenLibrary |
|
|
84
|
+
| **Government** | OpenStates, USAspending, CourtListener, NIST NVD, Library of Congress |
|
|
85
|
+
| **Public Data** | Earthquake (USGS), NOAA Weather, GBIF Biodiversity, World Bank, WHO, Eurostat |
|
|
86
|
+
| **Utility** | OpenStreetMap geocoding, Reference Data (constants, timezones, units), WSDOT |
|
|
87
|
+
|
|
88
|
+
## Getting started
|
|
89
|
+
|
|
90
|
+
### Public Hosted Instance
|
|
91
|
+
|
|
92
|
+
A public instance is available at `https://cyanheads.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
|
|
18
93
|
|
|
19
94
|
```json
|
|
20
95
|
{
|
|
21
96
|
"mcpServers": {
|
|
22
97
|
"cyanheads": {
|
|
23
|
-
"type": "
|
|
98
|
+
"type": "streamable-http",
|
|
24
99
|
"url": "https://cyanheads.caseyjhand.com/mcp"
|
|
25
100
|
}
|
|
26
101
|
}
|
|
27
102
|
}
|
|
28
103
|
```
|
|
29
104
|
|
|
30
|
-
|
|
105
|
+
For Claude Code:
|
|
31
106
|
|
|
32
107
|
```sh
|
|
33
|
-
claude mcp add --transport
|
|
108
|
+
claude mcp add --transport http cyanheads https://cyanheads.caseyjhand.com/mcp
|
|
34
109
|
```
|
|
35
110
|
|
|
36
|
-
###
|
|
111
|
+
### Self-Hosted / Local
|
|
37
112
|
|
|
38
|
-
|
|
113
|
+
Add the following to your MCP client configuration file.
|
|
39
114
|
|
|
40
115
|
```json
|
|
41
116
|
{
|
|
42
117
|
"mcpServers": {
|
|
43
118
|
"cyanheads": {
|
|
44
|
-
"type": "
|
|
45
|
-
"
|
|
119
|
+
"type": "stdio",
|
|
120
|
+
"command": "bunx",
|
|
121
|
+
"args": ["@cyanheads/cyanheads-mcp-server@latest"],
|
|
122
|
+
"env": {
|
|
123
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
124
|
+
"MCP_LOG_LEVEL": "info"
|
|
125
|
+
}
|
|
46
126
|
}
|
|
47
127
|
}
|
|
48
128
|
}
|
|
49
129
|
```
|
|
50
130
|
|
|
51
|
-
|
|
131
|
+
Or with npx (no Bun required):
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"mcpServers": {
|
|
136
|
+
"cyanheads": {
|
|
137
|
+
"type": "stdio",
|
|
138
|
+
"command": "npx",
|
|
139
|
+
"args": ["-y", "@cyanheads/cyanheads-mcp-server@latest"],
|
|
140
|
+
"env": {
|
|
141
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
142
|
+
"MCP_LOG_LEVEL": "info"
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
52
148
|
|
|
53
|
-
|
|
149
|
+
Or with Docker:
|
|
54
150
|
|
|
55
151
|
```json
|
|
56
152
|
{
|
|
57
|
-
"
|
|
58
|
-
"
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
153
|
+
"mcpServers": {
|
|
154
|
+
"cyanheads": {
|
|
155
|
+
"type": "stdio",
|
|
156
|
+
"command": "docker",
|
|
157
|
+
"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cyanheads-mcp-server:latest"]
|
|
158
|
+
}
|
|
62
159
|
}
|
|
63
160
|
}
|
|
64
161
|
```
|
|
65
162
|
|
|
66
|
-
|
|
163
|
+
For Streamable HTTP, set the transport and start the server:
|
|
67
164
|
|
|
68
|
-
|
|
165
|
+
```sh
|
|
166
|
+
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
|
|
167
|
+
# Server listens at http://localhost:3010/mcp
|
|
168
|
+
```
|
|
69
169
|
|
|
70
|
-
|
|
71
|
-
|:--|:--|
|
|
72
|
-
| "search recent arxiv papers about quantum computing" | `arxiv_search` (arxiv-mcp-server), via semantic match on "research papers" |
|
|
73
|
-
| "look up earthquake activity in California" | `earthquake_search` (earthquake-mcp-server) |
|
|
74
|
-
| "what server handles federal spending data?" | `usaspending-mcp-server` (scope: servers) |
|
|
75
|
-
| "find a tool that resolves a place name to coordinates" | `openstreetmap_geocode` (openstreetmap-mcp-server) |
|
|
76
|
-
| "how do I add the bioRxiv server to Cursor?" | Install snippet via `cyanheads_describe` |
|
|
170
|
+
### Prerequisites
|
|
77
171
|
|
|
78
|
-
|
|
172
|
+
- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
|
|
79
173
|
|
|
80
|
-
|
|
174
|
+
### Installation
|
|
81
175
|
|
|
82
|
-
|
|
176
|
+
1. **Clone the repository:**
|
|
83
177
|
|
|
84
|
-
|
|
178
|
+
```sh
|
|
179
|
+
git clone https://github.com/cyanheads/cyanheads-mcp-server.git
|
|
180
|
+
```
|
|
85
181
|
|
|
86
|
-
|
|
87
|
-
|:--|:--|
|
|
88
|
-
| **Research** | arXiv, bioRxiv, ORCID, Crossref, Wikipedia, Wikidata, OpenLibrary |
|
|
89
|
-
| **Government** | OpenStates, USAspending, CourtListener, NIST NVD, Library of Congress |
|
|
90
|
-
| **Public Data** | Earthquake (USGS), NOAA Weather, GBIF Biodiversity, World Bank, WHO, Eurostat |
|
|
91
|
-
| **Utility** | OpenStreetMap geocoding, Reference Data (constants, timezones, units), WSDOT |
|
|
182
|
+
2. **Navigate into the directory:**
|
|
92
183
|
|
|
93
|
-
|
|
184
|
+
```sh
|
|
185
|
+
cd cyanheads-mcp-server
|
|
186
|
+
```
|
|
94
187
|
|
|
95
|
-
|
|
188
|
+
3. **Install dependencies:**
|
|
96
189
|
|
|
97
|
-
|
|
190
|
+
```sh
|
|
191
|
+
bun install
|
|
192
|
+
```
|
|
98
193
|
|
|
99
|
-
|
|
194
|
+
## Configuration
|
|
100
195
|
|
|
101
|
-
|
|
102
|
-
- **`cyanheads_describe`** returns the description, connection URL, and per-client install snippet for any tool or server name.
|
|
196
|
+
All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Every variable has a sensible default — out of the box, the server points at the canonical cyanheads fleet.
|
|
103
197
|
|
|
104
|
-
|
|
198
|
+
| Variable | Description | Default |
|
|
199
|
+
|:---|:---|:---|
|
|
200
|
+
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
|
|
201
|
+
| `MCP_HTTP_PORT` | HTTP server port | `3010` |
|
|
202
|
+
| `MCP_HTTP_HOST` | HTTP server bind host | `127.0.0.1` |
|
|
203
|
+
| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted | `/mcp` |
|
|
204
|
+
| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
|
|
205
|
+
| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
|
|
206
|
+
| `CATALOG_URL` | Remote fleet.json endpoint (schema v2 with baked embeddings). Override to front your own fleet. | `https://caseyjhand.com/fleet.json` |
|
|
207
|
+
| `CATALOG_FETCH_TIMEOUT_MS` | Per-request timeout for fleet.json fetches in ms | `10000` |
|
|
208
|
+
| `CATALOG_REFRESH_SECONDS` | Background poll interval for fleet.json refresh. `0` disables. | `3600` |
|
|
209
|
+
| `EMBEDDING_MODEL_ID` | Hugging Face model id for query embedding. Must match `fleet.json.embeddingModel`. | `Snowflake/snowflake-arctic-embed-m-v1.5` |
|
|
210
|
+
| `SIMILARITY_FLOOR` | Cosine similarity cutoff for `cyanheads_search` results (0-1) | `0.3` |
|
|
211
|
+
| `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
|
|
105
212
|
|
|
106
|
-
|
|
213
|
+
To point at a different catalog, change `CATALOG_URL` to your own hosted JSON file. See [`docs/design.md`](./docs/design.md) for the producer-side script and schema.
|
|
107
214
|
|
|
108
|
-
##
|
|
215
|
+
## Running the server
|
|
109
216
|
|
|
110
|
-
|
|
217
|
+
### Local development
|
|
111
218
|
|
|
112
|
-
|
|
113
|
-
git clone https://github.com/cyanheads/cyanheads-mcp-server.git
|
|
114
|
-
cd cyanheads-mcp-server
|
|
115
|
-
bun install
|
|
116
|
-
bun run build
|
|
117
|
-
bun run start:http
|
|
118
|
-
```
|
|
219
|
+
- **Build and run the production version**:
|
|
119
220
|
|
|
120
|
-
|
|
221
|
+
```sh
|
|
222
|
+
# One-time build
|
|
223
|
+
bun run rebuild
|
|
121
224
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
| `SIMILARITY_FLOOR` | `0.3` | Cosine similarity threshold below which results are dropped. |
|
|
128
|
-
| `MCP_TRANSPORT_TYPE` | `stdio` | `stdio` or `http`. |
|
|
129
|
-
| `MCP_HTTP_PORT` | `3000` | HTTP port when transport is `http`. |
|
|
225
|
+
# Run the built server
|
|
226
|
+
bun run start:http
|
|
227
|
+
# or
|
|
228
|
+
bun run start:stdio
|
|
229
|
+
```
|
|
130
230
|
|
|
131
|
-
|
|
231
|
+
- **Run checks and tests**:
|
|
232
|
+
```sh
|
|
233
|
+
bun run devcheck # Lints, formats, type-checks, runs MCP and packaging linters
|
|
234
|
+
bun run test # Runs the test suite
|
|
235
|
+
```
|
|
132
236
|
|
|
133
|
-
|
|
237
|
+
## Project structure
|
|
238
|
+
|
|
239
|
+
| Directory | Purpose |
|
|
240
|
+
|:---|:---|
|
|
241
|
+
| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Two tools — `cyanheads_search` and `cyanheads_describe`. |
|
|
242
|
+
| `src/services/catalog` | Catalog service — remote fleet.json provider with atomic-swap refresh, vector index, snippet builders. |
|
|
243
|
+
| `src/services/embeddings` | Embedding runtime — query-time inference via `@huggingface/transformers`, with an injectable interface for deterministic tests. |
|
|
244
|
+
| `src/config` | Server-specific environment variable parsing and validation with Zod. |
|
|
245
|
+
| `tests/` | Unit and integration tests, mirroring the `src/` structure. |
|
|
246
|
+
| `docs/` | Design doc and schema reference. |
|
|
247
|
+
|
|
248
|
+
## Development guide
|
|
134
249
|
|
|
135
|
-
|
|
250
|
+
See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
|
|
136
251
|
|
|
137
|
-
-
|
|
138
|
-
-
|
|
139
|
-
-
|
|
252
|
+
- Handlers throw, framework catches — no `try/catch` in tool logic
|
|
253
|
+
- Use `ctx.log` for logging, `ctx.state` for storage
|
|
254
|
+
- Register new tools in `src/mcp-server/tools/definitions/index.ts`
|
|
255
|
+
|
|
256
|
+
## Contributing
|
|
257
|
+
|
|
258
|
+
Issues and pull requests are welcome. Run checks and tests before submitting:
|
|
259
|
+
|
|
260
|
+
```sh
|
|
261
|
+
bun run devcheck
|
|
262
|
+
bun run test
|
|
263
|
+
```
|
|
140
264
|
|
|
141
265
|
## License
|
|
142
266
|
|
|
143
|
-
Apache 2.0. See [LICENSE](./LICENSE).
|
|
267
|
+
This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "README rewrite to match pubmed gold standard, .mcpb bundle restored for Claude Desktop one-click install, embeddings cache dir fix unblocks Docker non-root user, server.json advertises hosted endpoint via remotes[]"
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.1.4 — 2026-05-28
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **`manifest.json`** + **`.mcpbignore`** + `bun run bundle` script restore the `.mcpb` packaging path. The `Install in Claude Desktop` badge in the README now resolves to `releases/latest/download/cyanheads-mcp-server.mcpb` and one-click-installs into Claude Desktop without manual JSON editing. `manifest.json` exposes `CATALOG_URL` and `SIMILARITY_FLOOR` as `user_config` knobs so users can override the default fleet or tighten the relevance cutoff at install time.
|
|
12
|
+
- **`scripts/lint-packaging.ts`** — env-var alignment linter between `manifest.json` and `server.json` (stdio package `environmentVariables[]`). Wired into `devcheck` (skips cleanly when `manifest.json` is absent).
|
|
13
|
+
- **`server.json` `remotes[]`** — advertises `https://cyanheads.caseyjhand.com/mcp` as a streamable-http endpoint so MCP Registry consumers can discover the hosted instance without reading the README.
|
|
14
|
+
- **README** — full rewrite to match the pubmed-mcp-server gold standard: centered hero with title + tool count, badge row (Version, License, Docker, MCP SDK, npm, TypeScript, Bun), one-click install badges (Claude Desktop `.mcpb`, Cursor deeplink, VS Code), hosted-endpoint callout, per-tool detail sections, project structure, and a configuration table covering every env var with its default.
|
|
15
|
+
|
|
16
|
+
## Changed
|
|
17
|
+
|
|
18
|
+
- **`server.json`** + **`package.json`** + **`manifest.json`** versions to `0.1.4`. `package.json` `files` array now includes `manifest.json` so it ships in the published tarball.
|
|
19
|
+
|
|
20
|
+
## Fixed
|
|
21
|
+
|
|
22
|
+
- **Embeddings runtime cache dir** — `@huggingface/transformers` defaults its model cache to a subpath inside its own `node_modules` install (`node_modules/@huggingface/transformers/.cache`). Containers that `bun install` as root then drop to a non-root runtime user (the production Dockerfile pattern) crash on first query with `EACCES: permission denied, mkdir`. `src/services/catalog/embeddings-runtime.ts` now sets `env.cacheDir` at import time to `HF_HOME` / `TRANSFORMERS_CACHE` if set, otherwise a per-OS `tmpdir/cyanheads-mcp-server/hf-cache` fallback that's always writable.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Rewrite install snippet builders — drop legacy SSE transport tag, emit correct per-client formats (claude-code/codex/cursor/curl/gemini/streamable-http) verified against the hosted endpoint"
|
|
3
|
+
breaking: true
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.1.5 — 2026-05-28
|
|
8
|
+
|
|
9
|
+
## Changed
|
|
10
|
+
|
|
11
|
+
- **`cyanheads_describe` install snippets** — full rewrite. The 0.1.4 builders emitted `type: "sse"` and `--transport sse`, which the hosted endpoint never actually spoke (it runs Streamable HTTP). Snippets pasted into client configs would either fail outright or fall back to legacy transport paths. New formats are derived from working reference commands and verified against `https://cyanheads.caseyjhand.com/mcp`:
|
|
12
|
+
|
|
13
|
+
| Client | Format |
|
|
14
|
+
|:--|:--|
|
|
15
|
+
| `claude-code` | `claude mcp add --transport http <name> <url>` |
|
|
16
|
+
| `codex` | `codex mcp add <name> --url <url>` |
|
|
17
|
+
| `cursor` | `mcpServers.<name>.{url}` (no `type` field — Cursor reads HTTP servers from URL alone) |
|
|
18
|
+
| `curl` | `initialize` POST with `MCP-Protocol-Version: 2025-11-25` for connectivity testing |
|
|
19
|
+
| `gemini` | `gemini mcp add --transport http <name> <url>` |
|
|
20
|
+
| `streamable-http` | `mcpServers.<name>.{type:"http", url}` — generic shape consumed by Claude Desktop, Cline, and `mcp-remote` |
|
|
21
|
+
|
|
22
|
+
- **`ClientId` union** — `'claude-desktop' | 'claude-code' | 'cursor' | 'cline'` → `'claude-code' | 'codex' | 'cursor' | 'curl' | 'gemini' | 'streamable-http'`. Claude Desktop and Cline both consume the generic `streamable-http` format, so a single `streamable-http` entry replaces the two client-specific ones. `codex`, `gemini`, and `curl` are new.
|
|
23
|
+
|
|
24
|
+
## Breaking
|
|
25
|
+
|
|
26
|
+
- **`cyanheads_describe` `client` parameter values changed.** Callers that pin `client: 'claude-desktop'` or `client: 'cline'` will get a Zod validation error. Use `client: 'streamable-http'` instead — same JSON shape, with the correct `type: "http"` field. `client: 'claude-code'` and `client: 'cursor'` still work but emit the corrected payload.
|
|
27
|
+
- **`InstallSnippet.client` values changed.** Consumers that switch on the client string need to map the old IDs to the new ones (or read every snippet and let payload-shape detection drive UI rendering).
|
|
28
|
+
|
|
29
|
+
## Fixed
|
|
30
|
+
|
|
31
|
+
- **Stale doc references to SSE transport** — `src/services/catalog/types.ts` (`endpoint` JSDoc), `src/mcp-server/tools/definitions/describe.tool.ts` (output field describe text), `docs/design.md` (supported-clients table + snippet examples + `ClientId` example). All now say Streamable HTTP.
|
|
@@ -14,10 +14,12 @@ export declare const describeTool: import("@cyanheads/mcp-ts-core").ToolDefiniti
|
|
|
14
14
|
tool: "tool";
|
|
15
15
|
}>>;
|
|
16
16
|
client: z.ZodOptional<z.ZodEnum<{
|
|
17
|
-
"claude-desktop": "claude-desktop";
|
|
18
17
|
"claude-code": "claude-code";
|
|
18
|
+
codex: "codex";
|
|
19
19
|
cursor: "cursor";
|
|
20
|
-
|
|
20
|
+
curl: "curl";
|
|
21
|
+
gemini: "gemini";
|
|
22
|
+
"streamable-http": "streamable-http";
|
|
21
23
|
}>>;
|
|
22
24
|
}, z.core.$strip>, z.ZodObject<{
|
|
23
25
|
result: z.ZodDiscriminatedUnion<[z.ZodObject<{
|
|
@@ -38,10 +40,12 @@ export declare const describeTool: import("@cyanheads/mcp-ts-core").ToolDefiniti
|
|
|
38
40
|
toolCount: z.ZodNumber;
|
|
39
41
|
installSnippets: z.ZodArray<z.ZodObject<{
|
|
40
42
|
client: z.ZodEnum<{
|
|
41
|
-
"claude-desktop": "claude-desktop";
|
|
42
43
|
"claude-code": "claude-code";
|
|
44
|
+
codex: "codex";
|
|
43
45
|
cursor: "cursor";
|
|
44
|
-
|
|
46
|
+
curl: "curl";
|
|
47
|
+
gemini: "gemini";
|
|
48
|
+
"streamable-http": "streamable-http";
|
|
45
49
|
}>;
|
|
46
50
|
label: z.ZodString;
|
|
47
51
|
payload: z.ZodString;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"describe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/describe.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,YAAY
|
|
1
|
+
{"version":3,"file":"describe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/describe.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8MvB,CAAC"}
|
|
@@ -29,7 +29,7 @@ export const describeTool = tool('cyanheads_describe', {
|
|
|
29
29
|
.describe('Whether name refers to a tool or server. Omit to auto-detect: names containing ' +
|
|
30
30
|
'underscores are treated as tools; names containing hyphens are treated as servers.'),
|
|
31
31
|
client: z
|
|
32
|
-
.enum(['claude-
|
|
32
|
+
.enum(['claude-code', 'codex', 'cursor', 'curl', 'gemini', 'streamable-http'])
|
|
33
33
|
.optional()
|
|
34
34
|
.describe('Return the install snippet for this specific client only. ' +
|
|
35
35
|
'Omit to return snippets for all supported clients.'),
|
|
@@ -51,7 +51,7 @@ export const describeTool = tool('cyanheads_describe', {
|
|
|
51
51
|
version: z.string().describe('Published version captured at fleet-generation time.'),
|
|
52
52
|
npm: z.string().describe('npm package name (e.g. "@cyanheads/arxiv-mcp-server").'),
|
|
53
53
|
github: z.string().describe('GitHub repository URL.'),
|
|
54
|
-
endpoint: z.string().describe('HTTP
|
|
54
|
+
endpoint: z.string().describe('Streamable HTTP endpoint for the hosted deployment.'),
|
|
55
55
|
auth: z
|
|
56
56
|
.string()
|
|
57
57
|
.describe('Auth requirement for the hosted deployment (currently always "none").'),
|
|
@@ -60,7 +60,7 @@ export const describeTool = tool('cyanheads_describe', {
|
|
|
60
60
|
.array(z
|
|
61
61
|
.object({
|
|
62
62
|
client: z
|
|
63
|
-
.enum(['claude-
|
|
63
|
+
.enum(['claude-code', 'codex', 'cursor', 'curl', 'gemini', 'streamable-http'])
|
|
64
64
|
.describe('MCP client this snippet targets.'),
|
|
65
65
|
label: z.string().describe('Human-readable install method label.'),
|
|
66
66
|
payload: z.string().describe('Install payload (JSON fragment or CLI command).'),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"describe.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/describe.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,oBAAoB,EAAE;IACrD,KAAK,EAAE,+BAA+B;IACtC,WAAW,EACT,8FAA8F;QAC9F,mEAAmE;QACnE,+FAA+F;QAC/F,kGAAkG;IACpG,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACzD,IAAI,EAAE,CAAC,8BAA8B,CAAC;IAEtC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CACP,kEAAkE;YAChE,2FAA2F,CAC9F;QACH,IAAI,EAAE,CAAC;aACJ,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;aACxB,QAAQ,EAAE;aACV,QAAQ,CACP,iFAAiF;YAC/E,oFAAoF,CACvF;QACH,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,
|
|
1
|
+
{"version":3,"file":"describe.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/describe.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"embeddings-runtime.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/embeddings-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;
|
|
1
|
+
{"version":3,"file":"embeddings-runtime.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/embeddings-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoBH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,6BAA8B,YAAW,kBAAkB;aAG1C,OAAO,EAAE,MAAM;IAF3C,OAAO,CAAC,UAAU,CAA0C;gBAEhC,OAAO,EAAE,MAAM;IAErC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAmCzF"}
|
|
@@ -6,9 +6,21 @@
|
|
|
6
6
|
* Matryoshka-truncates + L2-normalizes the output to match document vectors.
|
|
7
7
|
* @module services/catalog/embeddings-runtime
|
|
8
8
|
*/
|
|
9
|
+
import os from 'node:os';
|
|
10
|
+
import path from 'node:path';
|
|
9
11
|
import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
|
|
10
12
|
import { logger } from '@cyanheads/mcp-ts-core/utils';
|
|
11
|
-
import { pipeline } from '@huggingface/transformers';
|
|
13
|
+
import { env, pipeline } from '@huggingface/transformers';
|
|
14
|
+
/**
|
|
15
|
+
* Redirect the model cache out of the package's `node_modules/.cache` default
|
|
16
|
+
* (unwritable in containers that install deps as root then drop to a non-root
|
|
17
|
+
* runtime user). HF_HOME / TRANSFORMERS_CACHE honored when set; otherwise fall
|
|
18
|
+
* back to a writable per-OS temp directory.
|
|
19
|
+
*/
|
|
20
|
+
env.cacheDir =
|
|
21
|
+
process.env.HF_HOME ??
|
|
22
|
+
process.env.TRANSFORMERS_CACHE ??
|
|
23
|
+
path.join(os.tmpdir(), 'cyanheads-mcp-server', 'hf-cache');
|
|
12
24
|
export class TransformersEmbeddingsRuntime {
|
|
13
25
|
modelId;
|
|
14
26
|
_extractor = null;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"embeddings-runtime.js","sourceRoot":"","sources":["../../../src/services/catalog/embeddings-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AACtD,OAAO,EAAkC,QAAQ,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"embeddings-runtime.js","sourceRoot":"","sources":["../../../src/services/catalog/embeddings-runtime.ts"],"names":[],"mappings":"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"}
|
|
@@ -2,7 +2,15 @@
|
|
|
2
2
|
* @fileoverview Per-client install snippet factory registry.
|
|
3
3
|
* A plain Record mapping ClientId to a factory function that produces an InstallSnippet
|
|
4
4
|
* from a CatalogRecord. Snippets are derived at request time from the record's
|
|
5
|
-
* { name,
|
|
5
|
+
* { name, endpoint } fields — no precomputed snippet list lives in the catalog JSON.
|
|
6
|
+
*
|
|
7
|
+
* All fleet servers run Streamable HTTP — the legacy `sse` transport tag is not
|
|
8
|
+
* emitted. Per-client formats:
|
|
9
|
+
* - claude-code / gemini: `<cli> mcp add --transport http <name> <url>`
|
|
10
|
+
* - codex: `codex mcp add <name> --url <url>`
|
|
11
|
+
* - cursor: `mcpServers.<name>.{url}` (no `type` field)
|
|
12
|
+
* - streamable-http: `mcpServers.<name>.{type:"http", url}` (Claude Desktop, Cline, generic)
|
|
13
|
+
* - curl: `initialize` POST with `MCP-Protocol-Version` header
|
|
6
14
|
* @module services/catalog/snippets
|
|
7
15
|
*/
|
|
8
16
|
import type { CatalogRecord, ClientId, InstallSnippet } from './types.js';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"snippets.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/snippets.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"snippets.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,4EAA4E;AAC5E,KAAK,cAAc,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,cAAc,CAAC;AAkFhE,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,QAAQ,EAAE,cAAc,CAO7D,CAAC;AAEF,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,EAAE,CAExE"}
|
|
@@ -2,47 +2,94 @@
|
|
|
2
2
|
* @fileoverview Per-client install snippet factory registry.
|
|
3
3
|
* A plain Record mapping ClientId to a factory function that produces an InstallSnippet
|
|
4
4
|
* from a CatalogRecord. Snippets are derived at request time from the record's
|
|
5
|
-
* { name,
|
|
5
|
+
* { name, endpoint } fields — no precomputed snippet list lives in the catalog JSON.
|
|
6
|
+
*
|
|
7
|
+
* All fleet servers run Streamable HTTP — the legacy `sse` transport tag is not
|
|
8
|
+
* emitted. Per-client formats:
|
|
9
|
+
* - claude-code / gemini: `<cli> mcp add --transport http <name> <url>`
|
|
10
|
+
* - codex: `codex mcp add <name> --url <url>`
|
|
11
|
+
* - cursor: `mcpServers.<name>.{url}` (no `type` field)
|
|
12
|
+
* - streamable-http: `mcpServers.<name>.{type:"http", url}` (Claude Desktop, Cline, generic)
|
|
13
|
+
* - curl: `initialize` POST with `MCP-Protocol-Version` header
|
|
6
14
|
* @module services/catalog/snippets
|
|
7
15
|
*/
|
|
8
|
-
/**
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
client: 'claude-desktop',
|
|
12
|
-
label: 'Claude Desktop (JSON config)',
|
|
13
|
-
payload: JSON.stringify({ [record.name]: { type: 'sse', url: record.endpoint } }, null, 2),
|
|
14
|
-
};
|
|
15
|
-
}
|
|
16
|
-
/** Build the Claude Code CLI command. */
|
|
16
|
+
/** MCP protocol version pinned in the curl `initialize` snippet. */
|
|
17
|
+
const CURL_MCP_PROTOCOL_VERSION = '2025-11-25';
|
|
18
|
+
/** Claude Code CLI install command. */
|
|
17
19
|
function claudeCodeSnippet(record) {
|
|
18
20
|
return {
|
|
19
21
|
client: 'claude-code',
|
|
20
22
|
label: 'Claude Code (CLI)',
|
|
21
|
-
payload: `claude mcp add --transport
|
|
23
|
+
payload: `claude mcp add --transport http ${record.name} ${record.endpoint}`,
|
|
22
24
|
};
|
|
23
25
|
}
|
|
24
|
-
/**
|
|
26
|
+
/** OpenAI Codex CLI install command. */
|
|
27
|
+
function codexSnippet(record) {
|
|
28
|
+
return {
|
|
29
|
+
client: 'codex',
|
|
30
|
+
label: 'Codex (CLI)',
|
|
31
|
+
payload: `codex mcp add ${record.name} --url ${record.endpoint}`,
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
/** Cursor `.cursor/mcp.json` fragment (Cursor reads HTTP servers without a `type` field). */
|
|
25
35
|
function cursorSnippet(record) {
|
|
26
36
|
return {
|
|
27
37
|
client: 'cursor',
|
|
28
38
|
label: 'Cursor (mcp.json)',
|
|
29
|
-
payload: JSON.stringify({ mcpServers: { [record.name]: {
|
|
39
|
+
payload: JSON.stringify({ mcpServers: { [record.name]: { url: record.endpoint } } }, null, 2),
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/** curl `initialize` request — a connectivity probe, not an install. */
|
|
43
|
+
function curlSnippet(record) {
|
|
44
|
+
const body = JSON.stringify({
|
|
45
|
+
jsonrpc: '2.0',
|
|
46
|
+
id: 1,
|
|
47
|
+
method: 'initialize',
|
|
48
|
+
params: {
|
|
49
|
+
protocolVersion: CURL_MCP_PROTOCOL_VERSION,
|
|
50
|
+
capabilities: {},
|
|
51
|
+
clientInfo: { name: 'curl', version: '1.0.0' },
|
|
52
|
+
},
|
|
53
|
+
});
|
|
54
|
+
return {
|
|
55
|
+
client: 'curl',
|
|
56
|
+
label: 'curl (initialize probe)',
|
|
57
|
+
payload: [
|
|
58
|
+
`curl -X POST ${record.endpoint} \\`,
|
|
59
|
+
` -H "Content-Type: application/json" \\`,
|
|
60
|
+
` -H "MCP-Protocol-Version: ${CURL_MCP_PROTOCOL_VERSION}" \\`,
|
|
61
|
+
` -d '${body}'`,
|
|
62
|
+
].join('\n'),
|
|
30
63
|
};
|
|
31
64
|
}
|
|
32
|
-
/**
|
|
33
|
-
function
|
|
65
|
+
/** Gemini CLI install command. */
|
|
66
|
+
function geminiSnippet(record) {
|
|
67
|
+
return {
|
|
68
|
+
client: 'gemini',
|
|
69
|
+
label: 'Gemini (CLI)',
|
|
70
|
+
payload: `gemini mcp add --transport http ${record.name} ${record.endpoint}`,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Generic Streamable HTTP `mcpServers` block. Works for Claude Desktop, Cline,
|
|
75
|
+
* mcp-remote, and any other MCP client that consumes the standard config shape
|
|
76
|
+
* with `type: "http"`.
|
|
77
|
+
*/
|
|
78
|
+
function streamableHttpSnippet(record) {
|
|
34
79
|
return {
|
|
35
|
-
client: '
|
|
36
|
-
label: '
|
|
37
|
-
payload: JSON.stringify({ [record.name]: { type: '
|
|
80
|
+
client: 'streamable-http',
|
|
81
|
+
label: 'Streamable HTTP (Claude Desktop, Cline, generic)',
|
|
82
|
+
payload: JSON.stringify({ mcpServers: { [record.name]: { type: 'http', url: record.endpoint } } }, null, 2),
|
|
38
83
|
};
|
|
39
84
|
}
|
|
40
85
|
/** Registry of all supported clients. */
|
|
41
86
|
export const SNIPPET_REGISTRY = {
|
|
42
|
-
'claude-desktop': claudeDesktopSnippet,
|
|
43
87
|
'claude-code': claudeCodeSnippet,
|
|
88
|
+
codex: codexSnippet,
|
|
44
89
|
cursor: cursorSnippet,
|
|
45
|
-
|
|
90
|
+
curl: curlSnippet,
|
|
91
|
+
gemini: geminiSnippet,
|
|
92
|
+
'streamable-http': streamableHttpSnippet,
|
|
46
93
|
};
|
|
47
94
|
/** Generate install snippets for all supported clients for a given record. */
|
|
48
95
|
export function buildAllSnippets(record) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../../../src/services/catalog/snippets.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../../../src/services/catalog/snippets.ts"],"names":[],"mappings":"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"}
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* @module services/catalog/types
|
|
6
6
|
*/
|
|
7
7
|
/** Supported MCP client identifiers for install snippets. */
|
|
8
|
-
export type ClientId = 'claude-
|
|
8
|
+
export type ClientId = 'claude-code' | 'codex' | 'cursor' | 'curl' | 'gemini' | 'streamable-http';
|
|
9
9
|
/** Catalog category for a fleet server. */
|
|
10
10
|
export type CatalogCategory = 'research' | 'government' | 'public-data' | 'utility';
|
|
11
11
|
/** Single tool entry inside a CatalogRecord. */
|
|
@@ -28,10 +28,12 @@ export interface InstallSnippet {
|
|
|
28
28
|
label: string;
|
|
29
29
|
/**
|
|
30
30
|
* The install payload. Shape varies by client:
|
|
31
|
-
* - claude-
|
|
32
|
-
* -
|
|
33
|
-
* - cursor: JSON fragment for
|
|
34
|
-
* -
|
|
31
|
+
* - claude-code: CLI command (`claude mcp add --transport http <name> <url>`)
|
|
32
|
+
* - codex: CLI command (`codex mcp add <name> --url <url>`)
|
|
33
|
+
* - cursor: JSON fragment for `.cursor/mcp.json` mcpServers block (no `type` field)
|
|
34
|
+
* - curl: HTTP `initialize` request for connectivity testing
|
|
35
|
+
* - gemini: CLI command (`gemini mcp add --transport http <name> <url>`)
|
|
36
|
+
* - streamable-http: generic JSON fragment for any MCP HTTP client (Claude Desktop, Cline, mcp-remote)
|
|
35
37
|
*/
|
|
36
38
|
payload: string;
|
|
37
39
|
}
|
|
@@ -53,7 +55,7 @@ export interface CatalogRecord {
|
|
|
53
55
|
* `${displayName}\n${description}`. Length matches FleetPayload.embeddingDims.
|
|
54
56
|
*/
|
|
55
57
|
embedding: number[];
|
|
56
|
-
/** HTTP
|
|
58
|
+
/** Streamable HTTP endpoint — always present; the catalog covers hosted servers only. */
|
|
57
59
|
endpoint: string;
|
|
58
60
|
/** GitHub repository URL. */
|
|
59
61
|
github: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,6DAA6D;AAC7D,MAAM,MAAM,QAAQ,GAAG,
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/types.ts"],"names":[],"mappings":"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"}
|
package/manifest.json
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
{
|
|
2
|
+
"manifest_version": "0.3",
|
|
3
|
+
"name": "cyanheads-mcp-server",
|
|
4
|
+
"version": "0.1.5",
|
|
5
|
+
"description": "Fleet discovery for the cyanheads MCP ecosystem — semantic search + install snippets.",
|
|
6
|
+
"author": { "name": "cyanheads" },
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "https://github.com/cyanheads/cyanheads-mcp-server"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/cyanheads/cyanheads-mcp-server#readme",
|
|
12
|
+
"license": "Apache-2.0",
|
|
13
|
+
"server": {
|
|
14
|
+
"type": "node",
|
|
15
|
+
"entry_point": "dist/index.js",
|
|
16
|
+
"mcp_config": {
|
|
17
|
+
"command": "node",
|
|
18
|
+
"args": ["${__dirname}/dist/index.js"],
|
|
19
|
+
"env": {
|
|
20
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
21
|
+
"MCP_AUTH_MODE": "none",
|
|
22
|
+
"NODE_ENV": "production",
|
|
23
|
+
"CATALOG_URL": "${user_config.catalog_url}",
|
|
24
|
+
"SIMILARITY_FLOOR": "${user_config.similarity_floor}"
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"compatibility": {
|
|
29
|
+
"runtimes": { "node": ">=24.0.0" }
|
|
30
|
+
},
|
|
31
|
+
"tools_generated": true,
|
|
32
|
+
"user_config": {
|
|
33
|
+
"catalog_url": {
|
|
34
|
+
"type": "string",
|
|
35
|
+
"title": "Catalog URL",
|
|
36
|
+
"description": "Remote fleet.json endpoint (schema v2 with baked embeddings). Defaults to the canonical cyanheads fleet — override to point at your own hosted catalog.",
|
|
37
|
+
"required": false,
|
|
38
|
+
"default": "https://caseyjhand.com/fleet.json"
|
|
39
|
+
},
|
|
40
|
+
"similarity_floor": {
|
|
41
|
+
"type": "string",
|
|
42
|
+
"title": "Similarity Floor",
|
|
43
|
+
"description": "Cosine similarity cutoff for cyanheads_search results (0-1). Raise to require closer matches; lower to surface more candidates.",
|
|
44
|
+
"required": false,
|
|
45
|
+
"default": "0.3"
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cyanheads/cyanheads-mcp-server",
|
|
3
3
|
"mcpName": "io.github.cyanheads/cyanheads-mcp-server",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.5",
|
|
5
5
|
"description": "Fleet discovery for the cyanheads MCP ecosystem — semantic search + install snippets.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "dist/index.js",
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"CLAUDE.md",
|
|
18
18
|
"AGENTS.md",
|
|
19
19
|
"Dockerfile",
|
|
20
|
+
"manifest.json",
|
|
20
21
|
"server.json"
|
|
21
22
|
],
|
|
22
23
|
"author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/cyanheads-mcp-server#readme)",
|
|
@@ -34,6 +35,9 @@
|
|
|
34
35
|
"list-skills": "tsx scripts/list-skills.ts",
|
|
35
36
|
"format": "biome check --write --unsafe .",
|
|
36
37
|
"lint:mcp": "tsx scripts/lint-mcp.ts",
|
|
38
|
+
"lint:packaging": "tsx scripts/lint-packaging.ts",
|
|
39
|
+
"bundle": "tsx scripts/build.ts && npx -y @anthropic-ai/mcpb pack . dist/cyanheads-mcp-server.mcpb",
|
|
40
|
+
"publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
|
|
37
41
|
"changelog:build": "tsx scripts/build-changelog.ts",
|
|
38
42
|
"changelog:check": "tsx scripts/build-changelog.ts --check",
|
|
39
43
|
"test": "vitest run",
|
package/server.json
CHANGED
|
@@ -6,14 +6,20 @@
|
|
|
6
6
|
"url": "https://github.com/cyanheads/cyanheads-mcp-server",
|
|
7
7
|
"source": "github"
|
|
8
8
|
},
|
|
9
|
-
"version": "0.1.
|
|
9
|
+
"version": "0.1.5",
|
|
10
|
+
"remotes": [
|
|
11
|
+
{
|
|
12
|
+
"type": "streamable-http",
|
|
13
|
+
"url": "https://cyanheads.caseyjhand.com/mcp"
|
|
14
|
+
}
|
|
15
|
+
],
|
|
10
16
|
"packages": [
|
|
11
17
|
{
|
|
12
18
|
"registryType": "npm",
|
|
13
19
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
14
20
|
"identifier": "@cyanheads/cyanheads-mcp-server",
|
|
15
21
|
"runtimeHint": "node",
|
|
16
|
-
"version": "0.1.
|
|
22
|
+
"version": "0.1.5",
|
|
17
23
|
"packageArguments": [
|
|
18
24
|
{ "type": "positional", "value": "run" },
|
|
19
25
|
{ "type": "positional", "value": "start:stdio" }
|
|
@@ -62,7 +68,7 @@
|
|
|
62
68
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
63
69
|
"identifier": "@cyanheads/cyanheads-mcp-server",
|
|
64
70
|
"runtimeHint": "node",
|
|
65
|
-
"version": "0.1.
|
|
71
|
+
"version": "0.1.5",
|
|
66
72
|
"packageArguments": [
|
|
67
73
|
{ "type": "positional", "value": "run" },
|
|
68
74
|
{ "type": "positional", "value": "start:http" }
|