@causari/mcp-server 0.1.1 → 0.1.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.
- package/CHANGELOG.md +87 -0
- package/LICENSE +6 -0
- package/NOTICE +38 -15
- package/README.md +141 -50
- package/dist/{chunk-R5UFW6H7.js → chunk-P2UAUQ4G.js} +2 -1
- package/dist/cli.d.ts +18 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +49 -13
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +3 -209
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -10
- package/dist/index.js.map +1 -0
- package/dist/server.d.ts +13 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +68 -0
- package/dist/server.js.map +1 -0
- package/dist/smoke.d.ts +6 -0
- package/dist/smoke.d.ts.map +1 -0
- package/dist/smoke.js +168 -135
- package/dist/smoke.js.map +1 -0
- package/dist/tools.d.ts +27 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +306 -0
- package/dist/tools.js.map +1 -0
- package/dist/validate.d.ts +53 -0
- package/dist/validate.d.ts.map +1 -0
- package/dist/validate.js +126 -0
- package/dist/validate.js.map +1 -0
- package/dist/version.d.ts +13 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +13 -0
- package/dist/version.js.map +1 -0
- package/dist/worker.d.ts +25 -0
- package/dist/worker.d.ts.map +1 -0
- package/dist/worker.js +261 -0
- package/dist/worker.js.map +1 -0
- package/package.json +11 -8
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Changelog — @causari/mcp-server
|
|
2
|
+
|
|
3
|
+
All notable changes to the Causari MCP Server package are documented here.
|
|
4
|
+
|
|
5
|
+
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
|
|
6
|
+
the package uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## [0.1.3] — 2026-06-26 — Denser graph + opt-in data packs
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Opt-in data packs** — `npx @causari/mcp-server --pack <id>` (or
|
|
15
|
+
`CAUSARI_PACK=<id>`) merges a themed pack on top of the core CKG, queryable
|
|
16
|
+
through the same five tools. The default surface stays computing-only; packs
|
|
17
|
+
are explicit. First pack: `worldcup-2026` (the 2026 FIFA World Cup as a causal
|
|
18
|
+
map). A bad id fails loudly and degrades to the core graph. (See ADR-0018.)
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
|
|
22
|
+
- **Denser core graph** — the hottest developer verticals (Kubernetes, Docker,
|
|
23
|
+
React, Rust, PostgreSQL, OAuth, Python, Git, Go) gained cited causal links:
|
|
24
|
+
**470 → 497** confidence-scored links across the same 245 events, so first
|
|
25
|
+
multi-hop queries return richer chains.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## [0.1.2] — 2026-06-26 — Hardening pass
|
|
30
|
+
|
|
31
|
+
Reliability + correctness pass ahead of npm publish. No breaking changes to the
|
|
32
|
+
tool interface.
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
|
|
36
|
+
- **Data integrity** — four causal links (`linux→docker`,
|
|
37
|
+
`service_workers→cloudflare_workers`, `reactjs→react_native`,
|
|
38
|
+
`firebase_rtdb→firebase`) were defined twice across vertical seed files. The
|
|
39
|
+
store dedupes by link ID, so the live graph always served **470** distinct
|
|
40
|
+
links while README/exports advertised 457. Removed the redundant copies; the
|
|
41
|
+
graph and all advertised counts now agree at **245 events / 470 links**.
|
|
42
|
+
- **`predict_scenarios` returned empty** for reasonable inputs whose conditions
|
|
43
|
+
shared no keyword with the (sparse) forecast-event text. Lexical matching is
|
|
44
|
+
now a *preference*: prefer keyword-relevant forecasts, fall back to the full
|
|
45
|
+
horizon/domain set otherwise. Conditions still shape the historical basis.
|
|
46
|
+
|
|
47
|
+
### Added
|
|
48
|
+
|
|
49
|
+
- **Input validation** at every tool boundary — rejects wrong types, `NaN`,
|
|
50
|
+
`Infinity`, out-of-range numbers, empty required strings, unknown domain
|
|
51
|
+
enums, and non-object arguments with a clear, agent-readable message instead
|
|
52
|
+
of letting bad values reach the query engine. (25 unit tests.)
|
|
53
|
+
- **HTTP transport hardening** (Cloudflare Worker) — content-type check,
|
|
54
|
+
64 KiB body-size cap, JSON-RPC batch rejection, malformed-envelope handling,
|
|
55
|
+
and `ValidationError` surfaced as an `isError` tool result (so agents
|
|
56
|
+
self-correct) rather than a `-32603` transport fault. (18 integration tests.)
|
|
57
|
+
- **`LICENSE` (MIT)** and **`NOTICE`** files — documents the dual-license split:
|
|
58
|
+
server code MIT, bundled CKG dataset CC-BY-SA 4.0. Both ship in the tarball.
|
|
59
|
+
- **`test` / `test:unit` / `smoke` npm scripts** — runs validation + worker +
|
|
60
|
+
smoke suites (56 cases total).
|
|
61
|
+
|
|
62
|
+
### Changed
|
|
63
|
+
|
|
64
|
+
- **Version centralized** in `src/version.ts` (`VERSION`,
|
|
65
|
+
`MCP_PROTOCOL_VERSION`, `SERVER_NAME`), imported by cli/server/worker/health/
|
|
66
|
+
discovery to eliminate the previous four-place hardcoded `0.1.0` drift.
|
|
67
|
+
- **README** — corrected counts, replaced a drifted `transformer` sample with a
|
|
68
|
+
verified Tool reference section (concrete example + response for all five
|
|
69
|
+
tools), documented validated param ranges, and pointed the hosted endpoint at
|
|
70
|
+
`mcp.causari.ai` (noted as deploy-pending).
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## [0.1.0] — 2026-05-18 — Initial MCP server
|
|
75
|
+
|
|
76
|
+
Initial public-ready package.
|
|
77
|
+
|
|
78
|
+
### Added
|
|
79
|
+
|
|
80
|
+
- Five MCP tools over the Causal Knowledge Graph: `query_events`,
|
|
81
|
+
`causal_chain`, `historical_resonance`, `predict_scenarios`, and the
|
|
82
|
+
enterprise-tier `org_knowledge` stub.
|
|
83
|
+
- stdio transport (`cli.ts`) for local IDE use via `npx @causari/mcp-server`.
|
|
84
|
+
- Cloudflare Worker HTTP transport (`worker.ts`) implementing MCP Streamable
|
|
85
|
+
HTTP as a stateless JSON-RPC endpoint, with optional bearer auth.
|
|
86
|
+
- Bundled CKG seed: 245 events / 8 insight patterns across 9 tech verticals.
|
|
87
|
+
- Smoke test harness (`smoke.ts`).
|
package/LICENSE
CHANGED
|
@@ -19,3 +19,9 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
|
19
19
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
20
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
21
|
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
This license covers the @causari/mcp-server source code only. The bundled
|
|
26
|
+
Causal Knowledge Graph dataset is licensed separately under CC-BY-SA 4.0 —
|
|
27
|
+
see NOTICE.
|
package/NOTICE
CHANGED
|
@@ -1,23 +1,46 @@
|
|
|
1
1
|
Causari MCP Server
|
|
2
2
|
Copyright (c) 2026 Causari
|
|
3
3
|
|
|
4
|
-
This
|
|
4
|
+
This product bundles material under two distinct licenses.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
────────────────────────────────────────────────────────────────────────
|
|
7
|
+
1. Server code — MIT License
|
|
8
|
+
────────────────────────────────────────────────────────────────────────
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
open dataset and is licensed under the Creative Commons
|
|
14
|
-
Attribution-ShareAlike 4.0 International License (CC-BY-SA-4.0):
|
|
10
|
+
All source code in this package (@causari/mcp-server) — the MCP tool
|
|
11
|
+
definitions, transports (stdio CLI + Cloudflare Worker HTTP), input
|
|
12
|
+
validation, and output shaping — is licensed under the MIT License.
|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
See LICENSE for the full text.
|
|
17
15
|
|
|
18
|
-
Any reuse, redistribution, or adaptation of the data — including extracting
|
|
19
|
-
it from this package — requires attribution to Causari and must be shared
|
|
20
|
-
under the same CC-BY-SA-4.0 terms. The MIT license on the source code does
|
|
21
|
-
NOT grant rights to relicense or appropriate the bundled data.
|
|
22
16
|
|
|
23
|
-
|
|
17
|
+
────────────────────────────────────────────────────────────────────────
|
|
18
|
+
2. Bundled Causal Knowledge Graph dataset — CC-BY-SA 4.0
|
|
19
|
+
────────────────────────────────────────────────────────────────────────
|
|
20
|
+
|
|
21
|
+
This server bundles and serves a curated Causal Knowledge Graph (the
|
|
22
|
+
"Dataset") — 245 events, 497 causal links, and 8 insight patterns across
|
|
23
|
+
technology history. The Dataset is sourced from the @causari/ckg seed and
|
|
24
|
+
mirrored in the public causari-data repository.
|
|
25
|
+
|
|
26
|
+
The Dataset is licensed under the Creative Commons
|
|
27
|
+
Attribution-ShareAlike 4.0 International License (CC-BY-SA 4.0), NOT MIT.
|
|
28
|
+
|
|
29
|
+
You are free to share and adapt the Dataset, including commercially,
|
|
30
|
+
provided you:
|
|
31
|
+
- give appropriate credit to Causari and link to the license, and
|
|
32
|
+
- distribute any derivative dataset under CC-BY-SA 4.0.
|
|
33
|
+
|
|
34
|
+
Full license: https://creativecommons.org/licenses/by-sa/4.0/
|
|
35
|
+
Dataset source: https://github.com/causari/causari-data
|
|
36
|
+
|
|
37
|
+
Tool outputs returned by this server are derived from the Dataset. If you
|
|
38
|
+
redistribute or publish substantial portions of the Dataset (e.g. exporting
|
|
39
|
+
the graph), the CC-BY-SA 4.0 attribution and share-alike terms apply to that
|
|
40
|
+
data. Ordinary use of the MCP tools by an AI agent to answer questions does
|
|
41
|
+
not trigger redistribution obligations.
|
|
42
|
+
|
|
43
|
+
────────────────────────────────────────────────────────────────────────
|
|
44
|
+
|
|
45
|
+
Summary: the code is MIT (do what you like). The knowledge graph data is
|
|
46
|
+
CC-BY-SA 4.0 (credit Causari, share derivatives alike).
|
package/README.md
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
# @causari/mcp-server
|
|
2
2
|
|
|
3
|
-
> **Wikipedia for AI agents.** A Model Context Protocol server that gives Claude Code, Cursor, Windsurf — or any MCP-compatible AI agent — structured causal knowledge: **245 events,
|
|
3
|
+
> **Wikipedia for AI agents.** A Model Context Protocol server that gives Claude Code, Cursor, Windsurf — or any MCP-compatible AI agent — structured causal knowledge: **245 events, 497 causal links** with confidence scores, and 8 insight patterns across 9 verticals of technology history.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<!-- TODO: Replace with 10s hero GIF showing Claude Code calling causal_chain("kubernetes") -->
|
|
6
|
+
<!--  -->
|
|
6
7
|
|
|
7
8
|
### Install in 60 seconds
|
|
8
9
|
|
|
@@ -65,6 +66,121 @@ In Claude Code these surface as `mcp__causari__causal_chain` (and similar), depe
|
|
|
65
66
|
|
|
66
67
|
---
|
|
67
68
|
|
|
69
|
+
## Tool reference — with examples
|
|
70
|
+
|
|
71
|
+
Every example below is a real call against the bundled graph, with the response trimmed for readability. Inputs are validated at the boundary: out-of-range numbers, unknown domains, NaN, and empty required fields are rejected with a clear message the agent can act on.
|
|
72
|
+
|
|
73
|
+
### `query_events`
|
|
74
|
+
|
|
75
|
+
Search the graph by time window, domain, impact, or free text.
|
|
76
|
+
|
|
77
|
+
```jsonc
|
|
78
|
+
// arguments
|
|
79
|
+
{ "yearFrom": 1990, "yearTo": 2010, "domains": ["technology"], "minImpact": 0.85, "limit": 4 }
|
|
80
|
+
```
|
|
81
|
+
```jsonc
|
|
82
|
+
// response (trimmed)
|
|
83
|
+
{
|
|
84
|
+
"events": [
|
|
85
|
+
{ "id": "web", "title": "World Wide Web", "year": "1991", "impactScore": 0.92 },
|
|
86
|
+
{ "id": "linux", "title": "Linux Kernel", "year": "1991", "impactScore": 0.92 },
|
|
87
|
+
{ "id": "aws", "title": "AWS / Cloud Computing", "year": "2006", "impactScore": 0.88 }
|
|
88
|
+
],
|
|
89
|
+
"totalMatched": 7,
|
|
90
|
+
"truncated": true,
|
|
91
|
+
"hint": "7 events matched but only 4 returned. Use minImpact or domains to narrow."
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Params: `query` (free text), `yearFrom`/`yearTo` (integers, negative = BCE), `domains` (enum array), `minImpact` (0–1), `limit` (1–200, default 20).
|
|
96
|
+
|
|
97
|
+
### `causal_chain`
|
|
98
|
+
|
|
99
|
+
Trace cause→effect chains from a root event. The single most useful tool.
|
|
100
|
+
|
|
101
|
+
```jsonc
|
|
102
|
+
// arguments — "what did Docker enable?"
|
|
103
|
+
{ "event": "docker", "direction": "effects", "depth": 1 }
|
|
104
|
+
```
|
|
105
|
+
```jsonc
|
|
106
|
+
// response (trimmed)
|
|
107
|
+
{
|
|
108
|
+
"root": { "id": "docker", "title": "Docker", "year": "2013" },
|
|
109
|
+
"effects": [
|
|
110
|
+
{ "title": "Kubernetes", "relationship": "caused", "confidence": 0.9,
|
|
111
|
+
"evidence": "Kubernetes orchestrates Docker-style containers..." },
|
|
112
|
+
{ "title": "Microservices Architecture", "relationship": "enabled", "confidence": 0.8 }
|
|
113
|
+
],
|
|
114
|
+
"relatedPatterns": [ { "pattern": "Abstraction Layer Migration", "predictiveValue": 0.8 } ]
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Params: `event` (required — ID like `"docker"` or a title substring like `"industrial"`), `direction` (`causes` | `effects` | `both`, default `both`), `depth` (1–5, default 2), `minConfidence` (0–1). Returns `{ error }` with a `query_events` hint when the event can't be resolved.
|
|
119
|
+
|
|
120
|
+
### `historical_resonance`
|
|
121
|
+
|
|
122
|
+
Find historical patterns parallel to a present-day situation.
|
|
123
|
+
|
|
124
|
+
```jsonc
|
|
125
|
+
// arguments
|
|
126
|
+
{ "situation": "open protocol competing with a closed platform", "maxResults": 2 }
|
|
127
|
+
```
|
|
128
|
+
```jsonc
|
|
129
|
+
// response (trimmed)
|
|
130
|
+
{
|
|
131
|
+
"matches": [
|
|
132
|
+
{ "pattern": "Open vs Proprietary Substrate", "matchScore": 0.35, "predictiveValue": 0.75,
|
|
133
|
+
"exemplars": [ { "title": "TCP/IP", "year": "1983" }, { "title": "Linux Kernel", "year": "1991" } ] },
|
|
134
|
+
{ "pattern": "Information Democratization Cycle", "matchScore": 0.17, "predictiveValue": 0.85 }
|
|
135
|
+
]
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Params: `situation` (required free text), `domains` (enum array), `maxResults` (1–20, default 3). Returns a `hint` when nothing matches.
|
|
140
|
+
|
|
141
|
+
### `predict_scenarios`
|
|
142
|
+
|
|
143
|
+
Generate scenario branches from current conditions + historical patterns.
|
|
144
|
+
|
|
145
|
+
```jsonc
|
|
146
|
+
// arguments
|
|
147
|
+
{ "conditions": ["AI capability accelerating"], "domains": ["technology"], "horizon": 2040 }
|
|
148
|
+
```
|
|
149
|
+
```jsonc
|
|
150
|
+
// response (trimmed)
|
|
151
|
+
{
|
|
152
|
+
"scenarios": [
|
|
153
|
+
{ "name": "Convergent Acceleration", "probability": 0.71, "historicalBasis": ["Substrate Substitution"] },
|
|
154
|
+
{ "name": "Constrained Progress", "probability": 0.52 },
|
|
155
|
+
{ "name": "Discontinuous Shift", "probability": 0.41 }
|
|
156
|
+
],
|
|
157
|
+
"meta": { "matchedInsights": 5, "forecastEventsConsidered": 11,
|
|
158
|
+
"disclaimer": "Scenarios are derived from historical pattern matching, not guaranteed forecasts." }
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Params: `conditions` (required non-empty string array), `horizon` (integer year, default 2040), `domains` (enum array), `maxScenarios` (1–10, default 3). Treat output as structured hypotheses, not predictions.
|
|
163
|
+
|
|
164
|
+
### `org_knowledge` *(Enterprise tier)*
|
|
165
|
+
|
|
166
|
+
Query an organization's private CKG. Returns an explanatory stub until an org graph is provisioned.
|
|
167
|
+
|
|
168
|
+
```jsonc
|
|
169
|
+
// arguments
|
|
170
|
+
{ "query": "database migration decisions", "orgId": "acme" }
|
|
171
|
+
```
|
|
172
|
+
```jsonc
|
|
173
|
+
// response
|
|
174
|
+
{
|
|
175
|
+
"events": [], "causalContext": [], "available": false,
|
|
176
|
+
"message": "No org-scoped knowledge graph configured for this org. Enterprise tier feature — see ADR-0004 Phase 4."
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Params: `query` (required), `orgId` (required), `team` (optional), `yearFrom`/`yearTo` (optional integers).
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
68
184
|
## Quick start
|
|
69
185
|
|
|
70
186
|
### Option 1 — npm (recommended)
|
|
@@ -87,13 +203,15 @@ Point directly to the hosted Cloudflare Worker — nothing to install or run loc
|
|
|
87
203
|
{
|
|
88
204
|
"mcpServers": {
|
|
89
205
|
"causari": {
|
|
90
|
-
"url": "https://
|
|
206
|
+
"url": "https://mcp.causari.ai/mcp"
|
|
91
207
|
}
|
|
92
208
|
}
|
|
93
209
|
}
|
|
94
210
|
```
|
|
95
211
|
|
|
96
|
-
Works with any MCP client that supports HTTP transport (Claude Desktop, Cursor, Windsurf, etc.).
|
|
212
|
+
Works with any MCP client that supports HTTP transport (Claude Desktop, Cursor, Windsurf, etc.). The same Worker also serves `GET /health` (status + graph stats) and `GET /.well-known/mcp.json` (discovery manifest).
|
|
213
|
+
|
|
214
|
+
> The hosted endpoint at `mcp.causari.ai` is the production target. Until it is live, use Option 1 (`npx`) or Option 3 (from source) — both run the identical server locally.
|
|
97
215
|
|
|
98
216
|
### Option 3 — From source
|
|
99
217
|
|
|
@@ -124,49 +242,14 @@ You should see a structured response with nodes, confidence scores, and an evide
|
|
|
124
242
|
|
|
125
243
|
---
|
|
126
244
|
|
|
127
|
-
## Sample outputs
|
|
128
|
-
|
|
129
|
-
### `causal_chain` — root: "transformer", direction: "causes", depth: 2
|
|
130
|
-
|
|
131
|
-
```json
|
|
132
|
-
{
|
|
133
|
-
"root": { "id": "transformer", "title": "Transformer Architecture", "year": "2017" },
|
|
134
|
-
"causes": [
|
|
135
|
-
{
|
|
136
|
-
"id": "turing_m", "title": "Turing Machine", "year": "1950", "hop": 1,
|
|
137
|
-
"relationship": "enabled", "confidence": 0.8,
|
|
138
|
-
"evidence": "Computational substrate for all neural architectures traces to Turing-complete machines."
|
|
139
|
-
},
|
|
140
|
-
{
|
|
141
|
-
"id": "mcculloch_pitts", "title": "McCulloch-Pitts Neuron", "year": "1943", "hop": 2,
|
|
142
|
-
"relationship": "enabled", "confidence": 0.9,
|
|
143
|
-
"evidence": "First formal model of artificial neurons; the foundational abstraction."
|
|
144
|
-
}
|
|
145
|
-
],
|
|
146
|
-
"relatedPatterns": [
|
|
147
|
-
{
|
|
148
|
-
"pattern": "Substrate Substitution",
|
|
149
|
-
"description": "A capability historically running on substrate A migrates to substrate B once B becomes cheaper or more flexible.",
|
|
150
|
-
"predictiveValue": 0.78
|
|
151
|
-
}
|
|
152
|
-
]
|
|
153
|
-
}
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
### `historical_resonance` — situation: "rapid democratization of knowledge through new technology"
|
|
157
|
-
|
|
158
|
-
Matches **Information Democratization Cycle** (predictive value 0.85), with exemplars spanning Language → Writing → Printing Press → Internet → Transformers — giving the agent a calibrated historical scaffold to reason from.
|
|
159
|
-
|
|
160
|
-
---
|
|
161
|
-
|
|
162
245
|
## Status & roadmap
|
|
163
246
|
|
|
164
247
|
This is honest reporting, not marketing copy.
|
|
165
248
|
|
|
166
|
-
**Current data depth (as of 2026-
|
|
249
|
+
**Current data depth (as of 2026-06):**
|
|
167
250
|
|
|
168
251
|
- **245 events** across 9 verticals: AI history, computing, web ecosystem, cloud/devops, databases, AI/ML tooling, security, mobile, and civilizational foundations
|
|
169
|
-
- **
|
|
252
|
+
- **497 causal links** with evidence text + confidence scores calibrated per-link
|
|
170
253
|
- **8 insight patterns** (Abstraction Layer Migration, Standardization Cycle, Open vs Proprietary, Information Democratization Cycle, and more)
|
|
171
254
|
|
|
172
255
|
**Strong coverage:** Queries like `causal_chain("docker")`, `causal_chain("reactjs")`, `causal_chain("jwt")`, or `historical_resonance("microservices vs monolith")` return dense causal chains with evidence. Dev-term hit rate validated at 10/10.
|
|
@@ -179,21 +262,27 @@ This is honest reporting, not marketing copy.
|
|
|
179
262
|
|
|
180
263
|
**Roadmap:**
|
|
181
264
|
|
|
182
|
-
- ✅
|
|
265
|
+
- ✅ Cloudflare Worker HTTP transport — built, stateless, optional bearer auth (deploy pending)
|
|
266
|
+
- 🔜 Hosted endpoint live at `mcp.causari.ai` — deploy the Worker + attach the custom domain
|
|
183
267
|
- 🔜 API key + rate limiting — Pro tier
|
|
184
268
|
- 🔜 Embedding-based resonance — replace lexical match with semantic similarity
|
|
185
269
|
- 🔜 Org/Personal scope — user-curated private CKG via enterprise tier
|
|
186
270
|
|
|
187
271
|
---
|
|
188
272
|
|
|
189
|
-
##
|
|
273
|
+
## Tests
|
|
190
274
|
|
|
191
275
|
```bash
|
|
192
|
-
|
|
193
|
-
|
|
276
|
+
pnpm test # validation + worker transport + smoke (build included)
|
|
277
|
+
pnpm test:unit # validation + worker transport only (no build)
|
|
278
|
+
pnpm smoke # build, then the CKG query smoke test
|
|
194
279
|
```
|
|
195
280
|
|
|
196
|
-
|
|
281
|
+
`pnpm test` runs three suites:
|
|
282
|
+
|
|
283
|
+
- **validation** (25 cases) — every tool argument validator: type, range, NaN/Infinity, enum, empty-string, and domain-enum rejection.
|
|
284
|
+
- **worker transport** (18 cases) — the full MCP JSON-RPC flow plus hardening: content-type, body-size cap, batch rejection, malformed envelopes, unknown tools, and validation errors surfaced as `isError` results; auth on/off.
|
|
285
|
+
- **smoke** (12 cases) — CKG query correctness on known events (`printing`, `transformer`, `chatgpt`), fuzzy title resolution, and edge cases (missing event, depth cap), with a sample `causal_chain` printed.
|
|
197
286
|
|
|
198
287
|
---
|
|
199
288
|
|
|
@@ -224,7 +313,7 @@ Expected: `PASS: 10/10` with a sample causal chain printed. The smoke covers too
|
|
|
224
313
|
│ - types │ ← schema (Event, CausalLink, Insight)
|
|
225
314
|
│ - store │ ← in-memory + adjacency indexes
|
|
226
315
|
│ - query │ ← BFS, search, resonance, scenarios
|
|
227
|
-
│ - seed (9 verticals) │ ← 245 events,
|
|
316
|
+
│ - seed (9 verticals) │ ← 245 events, 497 links, 8 patterns
|
|
228
317
|
└──────────────────────────────┘
|
|
229
318
|
```
|
|
230
319
|
|
|
@@ -242,10 +331,12 @@ For server code contributions, file issues or PRs here.
|
|
|
242
331
|
|
|
243
332
|
## License
|
|
244
333
|
|
|
245
|
-
This package is
|
|
334
|
+
This package is dual-licensed:
|
|
335
|
+
|
|
336
|
+
- **Server code** — MIT. See [`LICENSE`](LICENSE). Do what you like.
|
|
337
|
+
- **Bundled Causal Knowledge Graph dataset** — CC-BY-SA 4.0. See [`NOTICE`](NOTICE). Credit Causari and share derivatives alike. Source: [causari/causari-data](https://github.com/causari/causari-data).
|
|
246
338
|
|
|
247
|
-
|
|
248
|
-
- **Bundled Causal Knowledge Graph data** (events, causal links, insight patterns compiled into `dist/`) — **CC-BY-SA 4.0**. Reuse of the data — including extracting it from this package — requires attribution and share-alike, even though it ships inside this MIT-licensed package. The MIT code license does not relicense the data. Source dataset: [`causari/causari-data`](https://github.com/causari/causari-data).
|
|
339
|
+
Ordinary use of the MCP tools by an agent does not trigger redistribution obligations; exporting or republishing substantial portions of the graph does. See [`NOTICE`](NOTICE) for details.
|
|
249
340
|
|
|
250
341
|
---
|
|
251
342
|
|
|
@@ -10,12 +10,13 @@ import {
|
|
|
10
10
|
CallToolRequestSchema,
|
|
11
11
|
ListToolsRequestSchema
|
|
12
12
|
} from "@modelcontextprotocol/sdk/types.js";
|
|
13
|
+
var SERVER_VERSION = "0.1.1";
|
|
13
14
|
function createCausariServer(opts = {}) {
|
|
14
15
|
const store = opts.store ?? new CKGStore(loadSeed());
|
|
15
16
|
const server = new Server(
|
|
16
17
|
{
|
|
17
18
|
name: "causari-mcp-server",
|
|
18
|
-
version:
|
|
19
|
+
version: SERVER_VERSION
|
|
19
20
|
},
|
|
20
21
|
{
|
|
21
22
|
capabilities: {
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Causari MCP Server — local CLI.
|
|
4
|
+
*
|
|
5
|
+
* Usage:
|
|
6
|
+
* causari-mcp # stdio (Claude Code, Cursor)
|
|
7
|
+
* npx @causari/mcp-server # same, no install
|
|
8
|
+
* npx @causari/mcp-server --pack worldcup-2026 # core CKG + a themed pack
|
|
9
|
+
*
|
|
10
|
+
* Configure in Claude Code .mcp.json:
|
|
11
|
+
* {
|
|
12
|
+
* "mcpServers": {
|
|
13
|
+
* "causari": { "command": "causari-mcp" }
|
|
14
|
+
* }
|
|
15
|
+
* }
|
|
16
|
+
*/
|
|
17
|
+
export {};
|
|
18
|
+
//# sourceMappingURL=cli.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}
|
package/dist/cli.js
CHANGED
|
@@ -1,18 +1,54 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
2
|
+
/**
|
|
3
|
+
* Causari MCP Server — local CLI.
|
|
4
|
+
*
|
|
5
|
+
* Usage:
|
|
6
|
+
* causari-mcp # stdio (Claude Code, Cursor)
|
|
7
|
+
* npx @causari/mcp-server # same, no install
|
|
8
|
+
* npx @causari/mcp-server --pack worldcup-2026 # core CKG + a themed pack
|
|
9
|
+
*
|
|
10
|
+
* Configure in Claude Code .mcp.json:
|
|
11
|
+
* {
|
|
12
|
+
* "mcpServers": {
|
|
13
|
+
* "causari": { "command": "causari-mcp" }
|
|
14
|
+
* }
|
|
15
|
+
* }
|
|
16
|
+
*/
|
|
17
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
18
|
+
import { createCausariServer } from './server.js';
|
|
19
|
+
/**
|
|
20
|
+
* Resolve an optional data pack to load alongside the core CKG, from
|
|
21
|
+
* `--pack <id>` / `--pack=<id>` or the `CAUSARI_PACK` env var. Undefined =
|
|
22
|
+
* the default computing-only surface.
|
|
23
|
+
*/
|
|
24
|
+
function resolvePack(argv) {
|
|
25
|
+
const flag = argv.indexOf('--pack');
|
|
26
|
+
if (flag >= 0 && argv[flag + 1])
|
|
27
|
+
return argv[flag + 1];
|
|
28
|
+
const eq = argv.find((a) => a.startsWith('--pack='));
|
|
29
|
+
if (eq)
|
|
30
|
+
return eq.slice('--pack='.length);
|
|
31
|
+
return process.env.CAUSARI_PACK || undefined;
|
|
32
|
+
}
|
|
9
33
|
async function main() {
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
34
|
+
const pack = resolvePack(process.argv.slice(2));
|
|
35
|
+
let server;
|
|
36
|
+
try {
|
|
37
|
+
server = createCausariServer({ pack });
|
|
38
|
+
if (pack)
|
|
39
|
+
process.stderr.write(`causari-mcp: loaded pack "${pack}" alongside the core CKG\n`);
|
|
40
|
+
}
|
|
41
|
+
catch (err) {
|
|
42
|
+
// A bad pack id must not take the server down — degrade to core + warn.
|
|
43
|
+
process.stderr.write(`causari-mcp: ${err instanceof Error ? err.message : String(err)} — serving core CKG only\n`);
|
|
44
|
+
server = createCausariServer();
|
|
45
|
+
}
|
|
46
|
+
const transport = new StdioServerTransport();
|
|
47
|
+
await server.connect(transport);
|
|
48
|
+
// Server now runs until stdin closes.
|
|
13
49
|
}
|
|
14
50
|
main().catch((err) => {
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
process.exit(1);
|
|
51
|
+
process.stderr.write(`causari-mcp fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
|
|
52
|
+
process.exit(1);
|
|
18
53
|
});
|
|
54
|
+
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAc;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACvD,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACrD,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,SAAS,CAAC;AAC/C,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,mBAAmB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACvC,IAAI,IAAI;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,IAAI,4BAA4B,CAAC,CAAC;IAChG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wEAAwE;QACxE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gBAAgB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAC7F,CAAC;QACF,MAAM,GAAG,mBAAmB,EAAE,CAAC;IACjC,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,sCAAsC;AACxC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
|