@prereason/mcp 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +100 -100
  2. package/LICENSE +21 -21
  3. package/README.md +219 -202
  4. package/bin/cli.js +109 -109
  5. package/package.json +61 -61
package/CHANGELOG.md CHANGED
@@ -1,100 +1,100 @@
1
- # Changelog
2
-
3
- ## 0.3.0 (2026-04-12)
4
-
5
- ### Added
6
- - OAuth 2.1 support for automatic API key provisioning on MCP connection
7
- - Server branding metadata (title, description, icons) for client connection cards
8
- - Centered README hero layout with improved visual hierarchy
9
- - Privacy Policy section in README
10
- - npm downloads and Node.js version badges
11
-
12
- ### Security
13
- - Harden OAuth proxy endpoints with input validation, rate limiting, and timeout handling
14
- - Sanitize upstream error responses on token exchange
15
-
16
- ### Fixed
17
- - HEAD /api/mcp returning 405 instead of 200
18
- - Metric count in README (38 -> 30)
19
- - cli.js version mismatch with package.json
20
-
21
- ## 0.2.1 (2026-03-30)
22
-
23
- - Add .mcp.json for Open Plugins / cursor.directory discovery
24
- - Include .mcp.json in npm package files
25
-
26
- ## 0.2.0 (2026-03-21)
27
-
28
- - Add Glama deployment support (Dockerfile build, inspection, release)
29
- - Add build script for container image builds
30
- - Add 6 MCP prompt templates (daily_market_briefing, risk_check, mining_profitability, macro_regime_check, correlation_scanner, weekly_recap)
31
- - Add 2 MCP resource catalogs (briefing_catalog, metric_catalog)
32
-
33
- ## 0.1.12 (2026-03-17)
34
-
35
- - Switch publish workflow to OIDC trusted publisher (no NPM_TOKEN needed)
36
- - Trigger on tag push (`v*`) instead of GitHub releases
37
- - Fix repository URL to canonical npm format
38
-
39
- ## 0.1.11 (2026-03-17)
40
-
41
- - Vocabulary alignment: "templates" → "briefings" across README, CHANGELOG, and tool references
42
- - Update published npm description to reference "briefings" instead of "templates"
43
-
44
- ## 0.1.10 (2026-03-15)
45
-
46
- - Enable SLSA provenance attestation via GitHub Actions publish workflow
47
- - Fix workflow placement: move from `packages/mcp/.github/` to repo root `.github/workflows/`
48
- - Switch publish trigger to `workflow_dispatch` for manual control
49
-
50
- ## 0.1.9 (2026-03-10)
51
-
52
- - Expand `socket.yml` to suppress all known-safe transitive dependency alerts from `@modelcontextprotocol/sdk`
53
- - Covers eval (ajv), shell (cross-spawn), filesystem (express/send), debug, dynamic require, unmaintained micro-packages, and more
54
-
55
- ## 0.1.8 (2026-03-05)
56
-
57
- - Remove `createRequire` / dynamic `require('../package.json')` — hardcode version constants
58
- - Eliminates Socket.dev "Dynamic require" and "Filesystem access" findings from our code
59
- - Add `socket.yml` for GitHub PR alert suppression of expected behaviors (network access, env vars)
60
-
61
- ## 0.1.7 (2026-03-04)
62
-
63
- - Pin `@modelcontextprotocol/sdk` to exact `1.27.1` (fixes transitive CVEs in hono and qs)
64
- - Update metric count from 26 to 30 (added 200D MA, distance from 200D MA, USDT market cap, USDT dominance)
65
- - Update `btc.momentum` description to reflect 200D MA support/resistance
66
- - Update `cross.regime` description to reflect USDT.D risk sentiment
67
-
68
- ## 0.1.6 (2026-02-25)
69
-
70
- - Fix description wording: replace "trend signals" with "trend interpretation"
71
- - Add SECURITY.md with vulnerability reporting policy
72
- - Add GitHub Actions CI workflow for provenance-signed npm publishing
73
- - Public source repo at https://github.com/PreReason/mcp
74
-
75
- ## 0.1.3 (2026-02-21)
76
-
77
- - Add `PREREASON_API_KEY` environment variable support (fixes Windows `cmd.exe` quoting crash)
78
- - Add `PREREASON_URL` environment variable for custom endpoint
79
- - Update all config examples to use `env` block (matches Stripe/Supabase pattern)
80
- - `--header` CLI args still supported for backward compatibility
81
-
82
- ## 0.1.2 (2026-02-21)
83
-
84
- - Fix Windows path resolution issue in Claude Desktop (rename `.mjs` → `.js` bin entry)
85
- - Add Windows troubleshooting section in README
86
-
87
- ## 0.1.1 (2026-02-21)
88
-
89
- - Add MIT LICENSE file
90
- - Enhance README with full briefing list, troubleshooting, and example prompts
91
- - Add CHANGELOG
92
-
93
- ## 0.1.0 (2026-02-20)
94
-
95
- - Initial release
96
- - stdio-to-Streamable HTTP bridge for Claude Desktop
97
- - Default URL: `https://api.prereason.com/api/mcp`
98
- - `--header Key:Value` flag for API key authentication
99
- - `--help` and `--version` flags
100
- - 5 MCP tools: get_context, get_metric, list_briefings, list_metrics, get_health
1
+ # Changelog
2
+
3
+ ## 0.3.0 (2026-04-12)
4
+
5
+ ### Added
6
+ - OAuth 2.1 support for automatic API key provisioning on MCP connection
7
+ - Server branding metadata (title, description, icons) for client connection cards
8
+ - Centered README hero layout with improved visual hierarchy
9
+ - Privacy Policy section in README
10
+ - npm downloads and Node.js version badges
11
+
12
+ ### Security
13
+ - Harden OAuth proxy endpoints with input validation, rate limiting, and timeout handling
14
+ - Sanitize upstream error responses on token exchange
15
+
16
+ ### Fixed
17
+ - HEAD /api/mcp returning 405 instead of 200
18
+ - Metric count in README (38 -> 30)
19
+ - cli.js version mismatch with package.json
20
+
21
+ ## 0.2.1 (2026-03-30)
22
+
23
+ - Add .mcp.json for Open Plugins / cursor.directory discovery
24
+ - Include .mcp.json in npm package files
25
+
26
+ ## 0.2.0 (2026-03-21)
27
+
28
+ - Add Glama deployment support (Dockerfile build, inspection, release)
29
+ - Add build script for container image builds
30
+ - Add 6 MCP prompt templates (daily_market_briefing, risk_check, mining_profitability, macro_regime_check, correlation_scanner, weekly_recap)
31
+ - Add 2 MCP resource catalogs (briefing_catalog, metric_catalog)
32
+
33
+ ## 0.1.12 (2026-03-17)
34
+
35
+ - Switch publish workflow to OIDC trusted publisher (no NPM_TOKEN needed)
36
+ - Trigger on tag push (`v*`) instead of GitHub releases
37
+ - Fix repository URL to canonical npm format
38
+
39
+ ## 0.1.11 (2026-03-17)
40
+
41
+ - Vocabulary alignment: "templates" → "briefings" across README, CHANGELOG, and tool references
42
+ - Update published npm description to reference "briefings" instead of "templates"
43
+
44
+ ## 0.1.10 (2026-03-15)
45
+
46
+ - Enable SLSA provenance attestation via GitHub Actions publish workflow
47
+ - Fix workflow placement: move from `packages/mcp/.github/` to repo root `.github/workflows/`
48
+ - Switch publish trigger to `workflow_dispatch` for manual control
49
+
50
+ ## 0.1.9 (2026-03-10)
51
+
52
+ - Expand `socket.yml` to suppress all known-safe transitive dependency alerts from `@modelcontextprotocol/sdk`
53
+ - Covers eval (ajv), shell (cross-spawn), filesystem (express/send), debug, dynamic require, unmaintained micro-packages, and more
54
+
55
+ ## 0.1.8 (2026-03-05)
56
+
57
+ - Remove `createRequire` / dynamic `require('../package.json')` — hardcode version constants
58
+ - Eliminates Socket.dev "Dynamic require" and "Filesystem access" findings from our code
59
+ - Add `socket.yml` for GitHub PR alert suppression of expected behaviors (network access, env vars)
60
+
61
+ ## 0.1.7 (2026-03-04)
62
+
63
+ - Pin `@modelcontextprotocol/sdk` to exact `1.27.1` (fixes transitive CVEs in hono and qs)
64
+ - Update metric count from 26 to 30 (added 200D MA, distance from 200D MA, USDT market cap, USDT dominance)
65
+ - Update `btc.momentum` description to reflect 200D MA support/resistance
66
+ - Update `cross.regime` description to reflect USDT.D risk sentiment
67
+
68
+ ## 0.1.6 (2026-02-25)
69
+
70
+ - Fix description wording: replace "trend signals" with "trend interpretation"
71
+ - Add SECURITY.md with vulnerability reporting policy
72
+ - Add GitHub Actions CI workflow for provenance-signed npm publishing
73
+ - Public source repo at https://github.com/PreReason/mcp
74
+
75
+ ## 0.1.3 (2026-02-21)
76
+
77
+ - Add `PREREASON_API_KEY` environment variable support (fixes Windows `cmd.exe` quoting crash)
78
+ - Add `PREREASON_URL` environment variable for custom endpoint
79
+ - Update all config examples to use `env` block (matches Stripe/Supabase pattern)
80
+ - `--header` CLI args still supported for backward compatibility
81
+
82
+ ## 0.1.2 (2026-02-21)
83
+
84
+ - Fix Windows path resolution issue in Claude Desktop (rename `.mjs` → `.js` bin entry)
85
+ - Add Windows troubleshooting section in README
86
+
87
+ ## 0.1.1 (2026-02-21)
88
+
89
+ - Add MIT LICENSE file
90
+ - Enhance README with full briefing list, troubleshooting, and example prompts
91
+ - Add CHANGELOG
92
+
93
+ ## 0.1.0 (2026-02-20)
94
+
95
+ - Initial release
96
+ - stdio-to-Streamable HTTP bridge for Claude Desktop
97
+ - Default URL: `https://api.prereason.com/api/mcp`
98
+ - `--header Key:Value` flag for API key authentication
99
+ - `--help` and `--version` flags
100
+ - 5 MCP tools: get_context, get_metric, list_briefings, list_metrics, get_health
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 PreReason
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 PreReason
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,202 +1,219 @@
1
- <div align="center">
2
-
3
- # @prereason/mcp
4
-
5
- [![npm version](https://img.shields.io/npm/v/@prereason/mcp.svg)](https://www.npmjs.com/package/@prereason/mcp)
6
- [![npm downloads](https://img.shields.io/npm/dm/@prereason/mcp.svg)](https://www.npmjs.com/package/@prereason/mcp)
7
- [![node version](https://img.shields.io/node/v/@prereason/mcp.svg)](https://nodejs.org)
8
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
9
- [![Glama Score](https://glama.ai/mcp/servers/PreReason/mcp/badges/score.svg)](https://glama.ai/mcp/servers/PreReason/mcp)
10
-
11
- **MCP server for [PreReason](https://www.prereason.com) - the Context API for financial agents.**
12
-
13
- Give your agent market context, not raw price feeds. 17 briefings covering BTC, macro,<br>
14
- cross-asset regimes, and liquidity - each with trend signals, confidence scores, and causal narratives.
15
-
16
- </div>
17
-
18
- ## Quick Start
19
-
20
- ### Option 1: Direct HTTP (Claude Code, Cursor, Windsurf, etc.)
21
-
22
- Clients that support remote MCP servers can connect directly with no bridge package needed.
23
-
24
- ```bash
25
- # Claude Code (CLI one-liner)
26
- claude mcp add prereason --transport http https://api.prereason.com/api/mcp
27
- ```
28
-
29
- Or add to `.mcp.json` / your client's MCP config:
30
-
31
- ```json
32
- {
33
- "mcpServers": {
34
- "prereason": {
35
- "type": "http",
36
- "url": "https://api.prereason.com/api/mcp",
37
- "headers": {
38
- "Authorization": "Bearer YOUR_API_KEY"
39
- }
40
- }
41
- }
42
- }
43
- ```
44
-
45
- ### Option 2: stdio bridge (Claude Desktop and other stdio-only clients)
46
-
47
- **Requires [Node.js 18+](https://nodejs.org)**
48
-
49
- Add to your MCP client config (e.g. `claude_desktop_config.json`):
50
-
51
- ```json
52
- {
53
- "mcpServers": {
54
- "prereason": {
55
- "command": "npx",
56
- "args": ["-y", "@prereason/mcp"],
57
- "env": {
58
- "PREREASON_API_KEY": "YOUR_API_KEY"
59
- }
60
- }
61
- }
62
- }
63
- ```
64
-
65
- Claude Desktop config file location:
66
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
67
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
68
-
69
- Restart your MCP client after editing the config. PreReason should appear with 5 tools.
70
-
71
- ## Get an API Key
72
-
73
- 1. Sign up at [prereason.com/signup](https://www.prereason.com/signup)
74
- 2. Go to Dashboard > Settings > API Keys
75
- 3. Copy your key (starts with `pr_live_`)
76
-
77
- ## 5 MCP Tools
78
-
79
- | Tool | Auth | Description |
80
- |------|------|-------------|
81
- | `list_briefings` | Open | List all 17 pre-reasoned market briefings with tier requirements |
82
- | `list_metrics` | Open | List all 30 available metrics across bitcoin, macro, and calculated categories |
83
- | `get_health` | Open | API health check, version, account tier |
84
- | `get_context` | Required | Fetch a pre-reasoned market briefing (markdown or JSON) |
85
- | `get_metric` | Required | Fetch a single metric with trend/signal/percentile |
86
-
87
- ## 17 Market Briefings
88
-
89
- ### Free (6 briefings)
90
- | Briefing | Description |
91
- |----------|-------------|
92
- | `btc.quick-check` | Minimal fast context: BTC + Net Liquidity + correlation |
93
- | `btc.context` | BTC + liquidity + hash ribbon + difficulty + momentum |
94
- | `macro.snapshot` | Fed balance, M2, treasury yields, VIX, net liquidity |
95
- | `cross.correlations` | BTC correlation matrix vs macro indicators |
96
- | `btc.pulse` | Volume, fees, mempool analysis |
97
- | `btc.grid-stress` | Epoch pace and difficulty adjustment forecast |
98
-
99
- ### Basic - $19.99/mo (5 briefings)
100
- | Briefing | Description |
101
- |----------|-------------|
102
- | `btc.momentum` | 200D MA support/resistance with 7d/30d/90d momentum and YTD percentiles |
103
- | `macro.liquidity` | Liquidity indicators with momentum analysis |
104
- | `btc.on-chain` | Hash rate, difficulty, fees, mempool health |
105
- | `cross.breadth` | Cross-asset breadth with SPY, DXY, VIX |
106
- | `btc.miner-survival` | Hashprice thermometer with miner stress scoring |
107
-
108
- ### Pro - $49.99/mo (6 briefings)
109
- | Briefing | Description |
110
- |----------|-------------|
111
- | `btc.full` | Complete market intelligence with all metrics and analysis |
112
- | `btc.factors` | Multi-factor attribution for BTC price movements |
113
- | `cross.regime` | Regime classification (risk-on/risk-off/transition) with USDT.D risk sentiment |
114
- | `fx.liquidity` | FX environment with DXY, treasury, and global liquidity |
115
- | `btc.energy` | Production cost model with gas input pressure |
116
- | `btc.treasury` | Corporate Bitcoin treasury intelligence from SEC filings |
117
-
118
- ## Example Prompts
119
-
120
- Once connected, try prompts like:
121
-
122
- - "What's the current BTC regime?"
123
- - "Show me the macro snapshot"
124
- - "What does the full context briefing say about market conditions?"
125
- - "Get the bitcoin price metric with trend analysis"
126
- - "What's the hash ribbon signal right now?"
127
- - "List available briefings"
128
-
129
- ## Troubleshooting
130
-
131
- ### "Server disconnected" error
132
- - Ensure Node.js 18+ is installed: `node --version`
133
- - Check your API key starts with `pr_live_`
134
- - Fully quit Claude Desktop (system tray > Quit) and reopen
135
-
136
- ### Tools not appearing
137
- - Restart Claude Desktop after editing config
138
- - Verify JSON syntax: `node -e "JSON.parse(require('fs').readFileSync('path/to/config','utf8'))"`
139
-
140
- ### Windows: "'C:\Program' is not recognized"
141
-
142
- If you still see this error, ensure you're using the `env` block (not `--header` args) as shown in Quick Start above. If the issue persists, install globally and use `node`:
143
-
144
- 1. Run: `npm install -g @prereason/mcp`
145
- 2. Use this config (replace `YOUR_USER` with your Windows username):
146
-
147
- ```json
148
- {
149
- "mcpServers": {
150
- "prereason": {
151
- "command": "node",
152
- "args": [
153
- "C:\\Users\\YOUR_USER\\AppData\\Roaming\\npm\\node_modules\\@prereason\\mcp\\bin\\cli.js"
154
- ],
155
- "env": {
156
- "PREREASON_API_KEY": "YOUR_API_KEY"
157
- }
158
- }
159
- }
160
- }
161
- ```
162
-
163
- ### Auth errors on get_context / get_metric
164
- - `list_briefings`, `list_metrics`, and `get_health` work without a key
165
- - `get_context` and `get_metric` require a valid API key
166
- - Get a free key at [prereason.com/signup](https://www.prereason.com/signup)
167
-
168
- ## Other MCP Clients
169
-
170
- If your client supports remote HTTP servers, use [Quick Start Option 1](#option-1-direct-http-claude-code-cursor-windsurf-etc) above. The stdio bridge package is only needed for clients that require stdio transport (e.g. Claude Desktop).
171
-
172
- ## CLI Usage
173
-
174
- ```bash
175
- # Using environment variable (recommended)
176
- PREREASON_API_KEY=pr_live_... npx @prereason/mcp
177
-
178
- # Using --header flag (backward compatible)
179
- npx @prereason/mcp --header "Authorization:Bearer YOUR_API_KEY"
180
-
181
- # Custom URL
182
- PREREASON_URL=https://custom.endpoint/mcp npx @prereason/mcp
183
-
184
- # Help
185
- npx @prereason/mcp --help
186
- ```
187
-
188
- ## Links
189
-
190
- - [Documentation](https://www.prereason.com/docs#mcp)
191
- - [Sign Up](https://www.prereason.com/signup)
192
- - [API Discovery](https://www.prereason.com/.well-known/mcp/server.json)
193
- - [Terms of Service](https://www.prereason.com/terms)
194
- - [Privacy Policy](https://www.prereason.com/privacy)
195
-
196
- ## Privacy Policy
197
-
198
- See [prereason.com/privacy](https://www.prereason.com/privacy) for data handling practices.
199
-
200
- ## License
201
-
202
- MIT
1
+ <div align="center">
2
+
3
+ # @prereason/mcp
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@prereason/mcp.svg)](https://www.npmjs.com/package/@prereason/mcp)
6
+ [![npm downloads](https://img.shields.io/npm/dm/@prereason/mcp.svg)](https://www.npmjs.com/package/@prereason/mcp)
7
+ [![node version](https://img.shields.io/node/v/@prereason/mcp.svg)](https://nodejs.org)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
9
+ [![Glama Score](https://glama.ai/mcp/servers/PreReason/mcp/badges/score.svg)](https://glama.ai/mcp/servers/PreReason/mcp)
10
+
11
+ **MCP server for [PreReason](https://www.prereason.com) - the Context API for financial agents.**
12
+
13
+ Give your agent market context, not raw price feeds. 17 briefings covering BTC, macro,<br>
14
+ cross-asset regimes, and liquidity - each with trend signals, confidence scores, and causal narratives.
15
+
16
+ </div>
17
+
18
+ ## Quick Start
19
+
20
+ ### Option 1: One-Click Connect (Claude.ai, ChatGPT, Cursor, Codex, Windsurf, VS Code Copilot)
21
+
22
+ Clients that support MCP OAuth can connect with no API key setup required. Add the server URL and the client handles the rest - you'll be prompted to sign in or create a free account, and your API key is provisioned automatically.
23
+
24
+ ```json
25
+ {
26
+ "mcpServers": {
27
+ "prereason": {
28
+ "type": "http",
29
+ "url": "https://api.prereason.com/api/mcp"
30
+ }
31
+ }
32
+ }
33
+ ```
34
+
35
+ No `Authorization` header needed - OAuth handles it.
36
+
37
+ ### Option 2: Direct HTTP with API Key (Claude Code, scripts, cron jobs)
38
+
39
+ For CLI tools or when you want to use an existing API key:
40
+
41
+ ```bash
42
+ # Claude Code (CLI one-liner)
43
+ claude mcp add prereason --transport http https://api.prereason.com/api/mcp
44
+ ```
45
+
46
+ Or with an explicit key in your MCP config:
47
+
48
+ ```json
49
+ {
50
+ "mcpServers": {
51
+ "prereason": {
52
+ "type": "http",
53
+ "url": "https://api.prereason.com/api/mcp",
54
+ "headers": {
55
+ "Authorization": "Bearer YOUR_API_KEY"
56
+ }
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ ### Option 3: stdio bridge (Claude Desktop and other stdio-only clients)
63
+
64
+ **Requires [Node.js 18+](https://nodejs.org)**
65
+
66
+ Add to your MCP client config (e.g. `claude_desktop_config.json`):
67
+
68
+ ```json
69
+ {
70
+ "mcpServers": {
71
+ "prereason": {
72
+ "command": "npx",
73
+ "args": ["-y", "@prereason/mcp"],
74
+ "env": {
75
+ "PREREASON_API_KEY": "YOUR_API_KEY"
76
+ }
77
+ }
78
+ }
79
+ }
80
+ ```
81
+
82
+ Claude Desktop config file location:
83
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
84
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
85
+
86
+ Restart your MCP client after editing the config. PreReason should appear with 5 tools.
87
+
88
+ ## Get an API Key
89
+
90
+ 1. Sign up at [prereason.com/signup](https://www.prereason.com/signup)
91
+ 2. Go to Dashboard > Settings > API Keys
92
+ 3. Copy your key (starts with `pr_live_`)
93
+
94
+ ## 5 MCP Tools
95
+
96
+ | Tool | Auth | Description |
97
+ |------|------|-------------|
98
+ | `list_briefings` | Open | List all 17 pre-reasoned market briefings with tier requirements |
99
+ | `list_metrics` | Open | List all 30 available metrics across bitcoin, macro, and calculated categories |
100
+ | `get_health` | Open | API health check, version, account tier |
101
+ | `get_context` | Required | Fetch a pre-reasoned market briefing (markdown or JSON) |
102
+ | `get_metric` | Required | Fetch a single metric with trend/signal/percentile |
103
+
104
+ ## 17 Market Briefings
105
+
106
+ ### Free (6 briefings)
107
+ | Briefing | Description |
108
+ |----------|-------------|
109
+ | `btc.quick-check` | Minimal fast context: BTC + Net Liquidity + correlation |
110
+ | `btc.context` | BTC + liquidity + hash ribbon + difficulty + momentum |
111
+ | `macro.snapshot` | Fed balance, M2, treasury yields, VIX, net liquidity |
112
+ | `cross.correlations` | BTC correlation matrix vs macro indicators |
113
+ | `btc.pulse` | Volume, fees, mempool analysis |
114
+ | `btc.grid-stress` | Epoch pace and difficulty adjustment forecast |
115
+
116
+ ### Basic - $19.99/mo (5 briefings)
117
+ | Briefing | Description |
118
+ |----------|-------------|
119
+ | `btc.momentum` | 200D MA support/resistance with 7d/30d/90d momentum and YTD percentiles |
120
+ | `macro.liquidity` | Liquidity indicators with momentum analysis |
121
+ | `btc.on-chain` | Hash rate, difficulty, fees, mempool health |
122
+ | `cross.breadth` | Cross-asset breadth with SPY, DXY, VIX |
123
+ | `btc.miner-survival` | Hashprice thermometer with miner stress scoring |
124
+
125
+ ### Pro - $49.99/mo (6 briefings)
126
+ | Briefing | Description |
127
+ |----------|-------------|
128
+ | `btc.full` | Complete market intelligence with all metrics and analysis |
129
+ | `btc.factors` | Multi-factor attribution for BTC price movements |
130
+ | `cross.regime` | Regime classification (risk-on/risk-off/transition) with USDT.D risk sentiment |
131
+ | `fx.liquidity` | FX environment with DXY, treasury, and global liquidity |
132
+ | `btc.energy` | Production cost model with gas input pressure |
133
+ | `btc.treasury` | Corporate Bitcoin treasury intelligence from SEC filings |
134
+
135
+ ## Example Prompts
136
+
137
+ Once connected, try prompts like:
138
+
139
+ - "What's the current BTC regime?"
140
+ - "Show me the macro snapshot"
141
+ - "What does the full context briefing say about market conditions?"
142
+ - "Get the bitcoin price metric with trend analysis"
143
+ - "What's the hash ribbon signal right now?"
144
+ - "List available briefings"
145
+
146
+ ## Troubleshooting
147
+
148
+ ### "Server disconnected" error
149
+ - Ensure Node.js 18+ is installed: `node --version`
150
+ - Check your API key starts with `pr_live_`
151
+ - Fully quit Claude Desktop (system tray > Quit) and reopen
152
+
153
+ ### Tools not appearing
154
+ - Restart Claude Desktop after editing config
155
+ - Verify JSON syntax: `node -e "JSON.parse(require('fs').readFileSync('path/to/config','utf8'))"`
156
+
157
+ ### Windows: "'C:\Program' is not recognized"
158
+
159
+ If you still see this error, ensure you're using the `env` block (not `--header` args) as shown in Quick Start above. If the issue persists, install globally and use `node`:
160
+
161
+ 1. Run: `npm install -g @prereason/mcp`
162
+ 2. Use this config (replace `YOUR_USER` with your Windows username):
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "prereason": {
168
+ "command": "node",
169
+ "args": [
170
+ "C:\\Users\\YOUR_USER\\AppData\\Roaming\\npm\\node_modules\\@prereason\\mcp\\bin\\cli.js"
171
+ ],
172
+ "env": {
173
+ "PREREASON_API_KEY": "YOUR_API_KEY"
174
+ }
175
+ }
176
+ }
177
+ }
178
+ ```
179
+
180
+ ### Auth errors on get_context / get_metric
181
+ - `list_briefings`, `list_metrics`, and `get_health` work without a key
182
+ - `get_context` and `get_metric` require a valid API key
183
+ - Get a free key at [prereason.com/signup](https://www.prereason.com/signup)
184
+
185
+ ## Other MCP Clients
186
+
187
+ If your client supports remote HTTP servers, use [Quick Start Option 1](#option-1-direct-http-claude-code-cursor-windsurf-etc) above. The stdio bridge package is only needed for clients that require stdio transport (e.g. Claude Desktop).
188
+
189
+ ## CLI Usage
190
+
191
+ ```bash
192
+ # Using environment variable (recommended)
193
+ PREREASON_API_KEY=pr_live_... npx @prereason/mcp
194
+
195
+ # Using --header flag (backward compatible)
196
+ npx @prereason/mcp --header "Authorization:Bearer YOUR_API_KEY"
197
+
198
+ # Custom URL
199
+ PREREASON_URL=https://custom.endpoint/mcp npx @prereason/mcp
200
+
201
+ # Help
202
+ npx @prereason/mcp --help
203
+ ```
204
+
205
+ ## Links
206
+
207
+ - [Documentation](https://www.prereason.com/docs#mcp)
208
+ - [Sign Up](https://www.prereason.com/signup)
209
+ - [API Discovery](https://www.prereason.com/.well-known/mcp/server.json)
210
+ - [Terms of Service](https://www.prereason.com/terms)
211
+ - [Privacy Policy](https://www.prereason.com/privacy)
212
+
213
+ ## Privacy Policy
214
+
215
+ See [prereason.com/privacy](https://www.prereason.com/privacy) for data handling practices.
216
+
217
+ ## License
218
+
219
+ MIT
package/bin/cli.js CHANGED
@@ -1,109 +1,109 @@
1
- #!/usr/bin/env node
2
- /**
3
- * @prereason/mcp — MCP bridge for Claude Desktop
4
- *
5
- * Connects Claude Desktop (stdio) to PreReason's Streamable HTTP MCP endpoint.
6
- *
7
- * Auth (preferred — works on all platforms):
8
- * Set PREREASON_API_KEY env var in your MCP client config.
9
- *
10
- * Usage:
11
- * npx @prereason/mcp
12
- * npx @prereason/mcp [--header Key:Value]...
13
- * npx @prereason/mcp <URL> [--header Key:Value]...
14
- *
15
- * Environment variables:
16
- * PREREASON_API_KEY Your API key (adds Authorization: Bearer header)
17
- * PREREASON_URL Override the default endpoint URL
18
- */
19
-
20
- import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
21
- import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
22
-
23
- // Keep in sync with package.json on each release
24
- const PKG_NAME = '@prereason/mcp';
25
- const PKG_VERSION = '0.3.0';
26
- const DEFAULT_URL = 'https://api.prereason.com/api/mcp';
27
-
28
- // --- Help / Version ---
29
- if (process.argv.includes('--help') || process.argv.includes('-h')) {
30
- process.stderr.write(`${PKG_NAME} v${PKG_VERSION}\n\n`);
31
- process.stderr.write('Usage:\n');
32
- process.stderr.write(' npx @prereason/mcp\n');
33
- process.stderr.write(' npx @prereason/mcp [--header Key:Value]...\n\n');
34
- process.stderr.write('Environment variables (recommended):\n');
35
- process.stderr.write(' PREREASON_API_KEY Your API key (adds Authorization: Bearer header)\n');
36
- process.stderr.write(' PREREASON_URL Override the default endpoint URL\n\n');
37
- process.stderr.write('Options:\n');
38
- process.stderr.write(' --header Key:Value Add HTTP header (can be repeated)\n');
39
- process.stderr.write(' --help, -h Show this help\n');
40
- process.stderr.write(' --version, -v Show version\n\n');
41
- process.stderr.write(`Default URL: ${DEFAULT_URL}\n`);
42
- process.exit(0);
43
- }
44
-
45
- if (process.argv.includes('--version') || process.argv.includes('-v')) {
46
- process.stderr.write(`${PKG_VERSION}\n`);
47
- process.exit(0);
48
- }
49
-
50
- // --- Read environment variables (preferred, avoids Windows cmd.exe quoting issues) ---
51
- let urlArg = process.env.PREREASON_URL || DEFAULT_URL;
52
- const headers = {};
53
-
54
- if (process.env.PREREASON_API_KEY) {
55
- headers['Authorization'] = `Bearer ${process.env.PREREASON_API_KEY}`;
56
- }
57
-
58
- // --- Parse CLI arguments (override env vars) ---
59
- for (let i = 2; i < process.argv.length; i++) {
60
- if (process.argv[i] === '--header' && process.argv[i + 1]) {
61
- const val = process.argv[++i];
62
- const colonIdx = val.indexOf(':');
63
- if (colonIdx > 0) {
64
- headers[val.slice(0, colonIdx).trim()] = val.slice(colonIdx + 1).trim();
65
- }
66
- } else if (!process.argv[i].startsWith('-')) {
67
- urlArg = process.argv[i];
68
- }
69
- }
70
-
71
- const url = new URL(urlArg);
72
-
73
- // --- Create transports ---
74
- const stdio = new StdioServerTransport();
75
- const http = new StreamableHTTPClientTransport(url, {
76
- requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
77
- });
78
-
79
- // --- Wire message routing ---
80
- stdio.onmessage = (msg) => {
81
- http.send(msg).catch((e) => {
82
- process.stderr.write(`[prereason:send] ${e.message}\n`);
83
- });
84
- };
85
-
86
- http.onmessage = (msg) => {
87
- stdio.send(msg).catch((e) => {
88
- process.stderr.write(`[prereason:recv] ${e.message}\n`);
89
- });
90
- };
91
-
92
- // --- Error handling ---
93
- stdio.onerror = (e) => process.stderr.write(`[prereason:stdio] ${e.message}\n`);
94
- http.onerror = (e) => process.stderr.write(`[prereason:http] ${e.message}\n`);
95
-
96
- // --- Graceful shutdown ---
97
- stdio.onclose = () => {
98
- http.close();
99
- process.exit(0);
100
- };
101
-
102
- http.onclose = () => {
103
- stdio.close();
104
- process.exit(0);
105
- };
106
-
107
- // --- Start ---
108
- await http.start();
109
- await stdio.start();
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @prereason/mcp — MCP bridge for Claude Desktop
4
+ *
5
+ * Connects Claude Desktop (stdio) to PreReason's Streamable HTTP MCP endpoint.
6
+ *
7
+ * Auth (preferred — works on all platforms):
8
+ * Set PREREASON_API_KEY env var in your MCP client config.
9
+ *
10
+ * Usage:
11
+ * npx @prereason/mcp
12
+ * npx @prereason/mcp [--header Key:Value]...
13
+ * npx @prereason/mcp <URL> [--header Key:Value]...
14
+ *
15
+ * Environment variables:
16
+ * PREREASON_API_KEY Your API key (adds Authorization: Bearer header)
17
+ * PREREASON_URL Override the default endpoint URL
18
+ */
19
+
20
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
21
+ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
22
+
23
+ // Keep in sync with package.json on each release
24
+ const PKG_NAME = '@prereason/mcp';
25
+ const PKG_VERSION = '0.3.1';
26
+ const DEFAULT_URL = 'https://api.prereason.com/api/mcp';
27
+
28
+ // --- Help / Version ---
29
+ if (process.argv.includes('--help') || process.argv.includes('-h')) {
30
+ process.stderr.write(`${PKG_NAME} v${PKG_VERSION}\n\n`);
31
+ process.stderr.write('Usage:\n');
32
+ process.stderr.write(' npx @prereason/mcp\n');
33
+ process.stderr.write(' npx @prereason/mcp [--header Key:Value]...\n\n');
34
+ process.stderr.write('Environment variables (recommended):\n');
35
+ process.stderr.write(' PREREASON_API_KEY Your API key (adds Authorization: Bearer header)\n');
36
+ process.stderr.write(' PREREASON_URL Override the default endpoint URL\n\n');
37
+ process.stderr.write('Options:\n');
38
+ process.stderr.write(' --header Key:Value Add HTTP header (can be repeated)\n');
39
+ process.stderr.write(' --help, -h Show this help\n');
40
+ process.stderr.write(' --version, -v Show version\n\n');
41
+ process.stderr.write(`Default URL: ${DEFAULT_URL}\n`);
42
+ process.exit(0);
43
+ }
44
+
45
+ if (process.argv.includes('--version') || process.argv.includes('-v')) {
46
+ process.stderr.write(`${PKG_VERSION}\n`);
47
+ process.exit(0);
48
+ }
49
+
50
+ // --- Read environment variables (preferred, avoids Windows cmd.exe quoting issues) ---
51
+ let urlArg = process.env.PREREASON_URL || DEFAULT_URL;
52
+ const headers = {};
53
+
54
+ if (process.env.PREREASON_API_KEY) {
55
+ headers['Authorization'] = `Bearer ${process.env.PREREASON_API_KEY}`;
56
+ }
57
+
58
+ // --- Parse CLI arguments (override env vars) ---
59
+ for (let i = 2; i < process.argv.length; i++) {
60
+ if (process.argv[i] === '--header' && process.argv[i + 1]) {
61
+ const val = process.argv[++i];
62
+ const colonIdx = val.indexOf(':');
63
+ if (colonIdx > 0) {
64
+ headers[val.slice(0, colonIdx).trim()] = val.slice(colonIdx + 1).trim();
65
+ }
66
+ } else if (!process.argv[i].startsWith('-')) {
67
+ urlArg = process.argv[i];
68
+ }
69
+ }
70
+
71
+ const url = new URL(urlArg);
72
+
73
+ // --- Create transports ---
74
+ const stdio = new StdioServerTransport();
75
+ const http = new StreamableHTTPClientTransport(url, {
76
+ requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
77
+ });
78
+
79
+ // --- Wire message routing ---
80
+ stdio.onmessage = (msg) => {
81
+ http.send(msg).catch((e) => {
82
+ process.stderr.write(`[prereason:send] ${e.message}\n`);
83
+ });
84
+ };
85
+
86
+ http.onmessage = (msg) => {
87
+ stdio.send(msg).catch((e) => {
88
+ process.stderr.write(`[prereason:recv] ${e.message}\n`);
89
+ });
90
+ };
91
+
92
+ // --- Error handling ---
93
+ stdio.onerror = (e) => process.stderr.write(`[prereason:stdio] ${e.message}\n`);
94
+ http.onerror = (e) => process.stderr.write(`[prereason:http] ${e.message}\n`);
95
+
96
+ // --- Graceful shutdown ---
97
+ stdio.onclose = () => {
98
+ http.close();
99
+ process.exit(0);
100
+ };
101
+
102
+ http.onclose = () => {
103
+ stdio.close();
104
+ process.exit(0);
105
+ };
106
+
107
+ // --- Start ---
108
+ await http.start();
109
+ await stdio.start();
package/package.json CHANGED
@@ -1,61 +1,61 @@
1
- {
2
- "name": "@prereason/mcp",
3
- "version": "0.3.0",
4
- "mcpName": "com.prereason/mcp",
5
- "type": "module",
6
- "description": "MCP server for PreReason — the Context API for financial agents. 17 pre-reasoned market briefings with trend signals, regime classification, confidence scores, and cross-asset correlations.",
7
- "bin": {
8
- "prereason-mcp": "./bin/cli.js"
9
- },
10
- "scripts": {
11
- "build": "echo 'Build complete'"
12
- },
13
- "files": [
14
- "bin",
15
- "README.md",
16
- "LICENSE",
17
- "CHANGELOG.md",
18
- ".mcp.json"
19
- ],
20
- "dependencies": {
21
- "@modelcontextprotocol/sdk": "1.27.1"
22
- },
23
- "engines": {
24
- "node": ">=18"
25
- },
26
- "keywords": [
27
- "mcp",
28
- "model-context-protocol",
29
- "claude",
30
- "bitcoin",
31
- "macro",
32
- "prereason",
33
- "ai",
34
- "llm",
35
- "finance",
36
- "crypto",
37
- "context-api",
38
- "market-briefing",
39
- "liquidity",
40
- "ai-agent",
41
- "pre-reasoned",
42
- "context-protocol"
43
- ],
44
- "author": {
45
- "name": "PreReason",
46
- "url": "https://www.prereason.com"
47
- },
48
- "license": "MIT",
49
- "homepage": "https://www.prereason.com/docs#mcp",
50
- "repository": {
51
- "type": "git",
52
- "url": "git+https://github.com/PreReason/mcp.git"
53
- },
54
- "bugs": {
55
- "url": "https://github.com/PreReason/mcp/issues"
56
- },
57
- "funding": {
58
- "type": "individual",
59
- "url": "https://www.prereason.com/signup"
60
- }
61
- }
1
+ {
2
+ "name": "@prereason/mcp",
3
+ "version": "0.3.1",
4
+ "mcpName": "io.github.PreReason/mcp",
5
+ "type": "module",
6
+ "description": "MCP server for PreReason — the Context API for financial agents. 17 pre-reasoned market briefings with trend signals, regime classification, confidence scores, and cross-asset correlations.",
7
+ "bin": {
8
+ "prereason-mcp": "./bin/cli.js"
9
+ },
10
+ "scripts": {
11
+ "build": "echo 'Build complete'"
12
+ },
13
+ "files": [
14
+ "bin",
15
+ "README.md",
16
+ "LICENSE",
17
+ "CHANGELOG.md",
18
+ ".mcp.json"
19
+ ],
20
+ "dependencies": {
21
+ "@modelcontextprotocol/sdk": "1.27.1"
22
+ },
23
+ "engines": {
24
+ "node": ">=18"
25
+ },
26
+ "keywords": [
27
+ "mcp",
28
+ "model-context-protocol",
29
+ "claude",
30
+ "bitcoin",
31
+ "macro",
32
+ "prereason",
33
+ "ai",
34
+ "llm",
35
+ "finance",
36
+ "crypto",
37
+ "context-api",
38
+ "market-briefing",
39
+ "liquidity",
40
+ "ai-agent",
41
+ "pre-reasoned",
42
+ "context-protocol"
43
+ ],
44
+ "author": {
45
+ "name": "PreReason",
46
+ "url": "https://www.prereason.com"
47
+ },
48
+ "license": "MIT",
49
+ "homepage": "https://www.prereason.com/docs#mcp",
50
+ "repository": {
51
+ "type": "git",
52
+ "url": "git+https://github.com/PreReason/mcp.git"
53
+ },
54
+ "bugs": {
55
+ "url": "https://github.com/PreReason/mcp/issues"
56
+ },
57
+ "funding": {
58
+ "type": "individual",
59
+ "url": "https://www.prereason.com/signup"
60
+ }
61
+ }