@j0hanz/cortex-mcp 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -245
- package/dist/engine/config.d.ts +0 -5
- package/dist/engine/config.d.ts.map +1 -1
- package/dist/engine/config.js +1 -14
- package/dist/engine/config.js.map +1 -1
- package/dist/engine/events.d.ts +4 -0
- package/dist/engine/events.d.ts.map +1 -1
- package/dist/engine/events.js.map +1 -1
- package/dist/engine/reasoner.d.ts.map +1 -1
- package/dist/engine/reasoner.js +97 -29
- package/dist/engine/reasoner.js.map +1 -1
- package/dist/engine/session-store.d.ts +20 -2
- package/dist/engine/session-store.d.ts.map +1 -1
- package/dist/engine/session-store.js +213 -14
- package/dist/engine/session-store.js.map +1 -1
- package/dist/lib/formatting.d.ts +6 -0
- package/dist/lib/formatting.d.ts.map +1 -0
- package/dist/lib/formatting.js +29 -0
- package/dist/lib/formatting.js.map +1 -0
- package/dist/lib/text.d.ts +1 -6
- package/dist/lib/text.d.ts.map +1 -1
- package/dist/lib/text.js +1 -6
- package/dist/lib/text.js.map +1 -1
- package/dist/lib/types.d.ts +2 -0
- package/dist/lib/types.d.ts.map +1 -1
- package/dist/lib/validators.d.ts +7 -0
- package/dist/lib/validators.d.ts.map +1 -0
- package/dist/lib/validators.js +21 -0
- package/dist/lib/validators.js.map +1 -0
- package/dist/prompts/index.js +3 -3
- package/dist/prompts/index.js.map +1 -1
- package/dist/resources/index.d.ts.map +1 -1
- package/dist/resources/index.js +33 -9
- package/dist/resources/index.js.map +1 -1
- package/dist/schemas/inputs.d.ts.map +1 -1
- package/dist/schemas/inputs.js +1 -1
- package/dist/schemas/inputs.js.map +1 -1
- package/dist/schemas/outputs.d.ts +10 -0
- package/dist/schemas/outputs.d.ts.map +1 -1
- package/dist/schemas/outputs.js +7 -2
- package/dist/schemas/outputs.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +10 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/reasoning-think.d.ts +1 -6
- package/dist/tools/reasoning-think.d.ts.map +1 -1
- package/dist/tools/reasoning-think.js +85 -40
- package/dist/tools/reasoning-think.js.map +1 -1
- package/package.json +10 -1
- package/dist/engine/index.d.ts +0 -6
- package/dist/engine/index.d.ts.map +0 -1
- package/dist/engine/index.js +0 -6
- package/dist/engine/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,186 +1,55 @@
|
|
|
1
1
|
# Cortex MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<!-- mcp-name: io.github.j0hanz/cortex-mcp -->
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@j0hanz/cortex-mcp) [](https://github.com/j0hanz/cortex-mcp/actions/workflows/release.yml) [](https://nodejs.org) [](https://www.typescriptlang.org) [](https://modelcontextprotocol.io) [](https://opensource.org/licenses/MIT)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## Overview
|
|
10
|
-
|
|
11
|
-
Cortex MCP is a reasoning engine that exposes a `reasoning.think` tool to perform multi-step analysis on complex queries. It supports three configurable depth levels (Basic, Normal, High), maintains session state for follow-up questions, and offers asynchronous task execution for long-running reasoning processes. All reasoning happens locally in-memory.
|
|
12
|
-
|
|
13
|
-
## Key Features
|
|
14
|
-
|
|
15
|
-
- **Multi-Level Reasoning**: Three distinct depth levels (`basic`, `normal`, `high`) with varying token budgets and thought counts.
|
|
16
|
-
- **Session Continuity**: Resume reasoning sessions by ID to maintain context across multiple turns.
|
|
17
|
-
- **Async Task Support**: Execute long-running reasoning as a background task with progress notifications.
|
|
18
|
-
- **Event-Driven Architecture**: Internal event emitter orchestrates session lifecycle and resource updates.
|
|
19
|
-
- **Real-time Resources**: Inspect active sessions and individual thought traces via MCP resources.
|
|
20
|
-
- **Strict Validation**: Zod-based schemas ensure type safety for all inputs and outputs.
|
|
21
|
-
|
|
22
|
-
## Tech Stack
|
|
7
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=cortex-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcortex-mcp%40latest%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=cortex-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcortex-mcp%40latest%22%5D%7D&quality=insiders)
|
|
23
8
|
|
|
24
|
-
|
|
25
|
-
- **Language**: TypeScript 5.9+
|
|
26
|
-
- **MCP SDK**: `@modelcontextprotocol/sdk` ^1.26.0
|
|
27
|
-
- **Validation**: `zod` ^4.3.6
|
|
28
|
-
- **Testing**: `node:test` (Native)
|
|
29
|
-
- **Package Manager**: npm
|
|
9
|
+
[](https://cursor.com/en/install-mcp?name=cortex-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29ydGV4LW1jcEBsYXRlc3QiXX0=)
|
|
30
10
|
|
|
31
|
-
|
|
11
|
+
Multi-level reasoning MCP server with configurable depth levels.
|
|
32
12
|
|
|
33
|
-
|
|
34
|
-
2. **Tool Handler**: `reasoning.think` validates input and initiates the reasoning planner.
|
|
35
|
-
3. **Engine**: The `reasoner` orchestrates thoughts based on the selected `level` configuration.
|
|
36
|
-
4. **State**: Sessions are stored in an in-memory `SessionStore` (LRU/TTL based).
|
|
37
|
-
5. **Resources**: Dynamic resource endpoints expose session data and markdown traces.
|
|
13
|
+
Cortex MCP exposes a single `reasoning.think` tool over stdio, providing structured, multi-step reasoning with session continuity, resource views, and optional task execution for long-running runs.
|
|
38
14
|
|
|
39
|
-
##
|
|
15
|
+
## Key Features
|
|
40
16
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
│ ├── server.ts # Server factory & setup
|
|
46
|
-
│ ├── engine/ # Reasoning logic and session store
|
|
47
|
-
│ ├── tools/ # Tool implementations (reasoning.think)
|
|
48
|
-
│ ├── resources/ # Resource endpoints
|
|
49
|
-
│ ├── prompts/ # Prompt templates
|
|
50
|
-
│ ├── schemas/ # Zod schemas (inputs/outputs)
|
|
51
|
-
│ └── lib/ # Utilities and types
|
|
52
|
-
├── scripts/ # Build and task runners
|
|
53
|
-
├── package.json
|
|
54
|
-
└── tsconfig.json
|
|
55
|
-
```
|
|
17
|
+
- Multi-level reasoning (`basic`, `normal`, `high`) with configurable thought counts and token budgets.
|
|
18
|
+
- Optional task execution with progress notifications for long-running requests.
|
|
19
|
+
- Resource endpoints for session lists, session detail, and markdown traces.
|
|
20
|
+
- Prompt helpers for building correct tool calls.
|
|
56
21
|
|
|
57
22
|
## Requirements
|
|
58
23
|
|
|
59
|
-
-
|
|
60
|
-
|
|
61
|
-
## Quickstart
|
|
62
|
-
|
|
63
|
-
Use `npx` to run the server directly without installation:
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
npx -y cortex-mcp@latest
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
## Installation
|
|
70
|
-
|
|
71
|
-
### NPX (Recommended)
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
npx -y cortex-mcp@latest
|
|
75
|
-
```
|
|
24
|
+
- Node.js >= 24
|
|
25
|
+
- An MCP client that supports stdio servers
|
|
76
26
|
|
|
77
|
-
|
|
27
|
+
## Quick Start
|
|
78
28
|
|
|
79
|
-
|
|
80
|
-
docker pull ghcr.io/j0hanz/cortex-mcp:latest
|
|
81
|
-
docker run --rm -i ghcr.io/j0hanz/cortex-mcp:latest
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
### From Source
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
git clone https://github.com/j0hanz/cortex-mcp.git
|
|
88
|
-
cd cortex-mcp
|
|
89
|
-
npm install
|
|
90
|
-
npm run build
|
|
91
|
-
node dist/index.js
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
## Configuration
|
|
95
|
-
|
|
96
|
-
### Environment Variables
|
|
97
|
-
|
|
98
|
-
No environment variables are strictly required for basic operation.
|
|
99
|
-
|
|
100
|
-
### Runtime Levels
|
|
101
|
-
|
|
102
|
-
The server is configured with the following reasoning levels (defined in `src/engine/config.ts`):
|
|
103
|
-
|
|
104
|
-
| Level | Token Budget | Thoughts Range |
|
|
105
|
-
| :------- | :----------- | :------------- |
|
|
106
|
-
| `basic` | 2,048 | 3–5 |
|
|
107
|
-
| `normal` | 8,192 | 6–10 |
|
|
108
|
-
| `high` | 32,768 | 15–25 |
|
|
109
|
-
|
|
110
|
-
## Usage
|
|
111
|
-
|
|
112
|
-
Configure your MCP client to start the server via stdio.
|
|
113
|
-
|
|
114
|
-
### Stdio Transport
|
|
115
|
-
|
|
116
|
-
Run the server process directly. Messages are sent over `stdin` and `stdout`.
|
|
117
|
-
|
|
118
|
-
## MCP Surface
|
|
119
|
-
|
|
120
|
-
### Tools
|
|
121
|
-
|
|
122
|
-
#### `reasoning.think`
|
|
123
|
-
|
|
124
|
-
Perform multi-level reasoning on a query.
|
|
125
|
-
|
|
126
|
-
| Parameter | Type | Required | Default | Description |
|
|
127
|
-
| :--------------- | :----- | :------- | :------ | :---------------------------------------------------------- |
|
|
128
|
-
| `query` | string | Yes | - | The question or problem to reason about (max 10,000 chars). |
|
|
129
|
-
| `level` | enum | Yes | - | Depth level: `basic`, `normal`, `high`. |
|
|
130
|
-
| `targetThoughts` | number | No | - | Optional exact step count (max 25). |
|
|
131
|
-
| `sessionId` | string | No | - | Session ID to continue a previous reasoning session. |
|
|
132
|
-
|
|
133
|
-
**Output Example**:
|
|
29
|
+
Standard config (works in most MCP clients):
|
|
134
30
|
|
|
135
31
|
```json
|
|
136
32
|
{
|
|
137
|
-
"
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
"generatedThoughts": 1,
|
|
143
|
-
"totalThoughts": 1,
|
|
144
|
-
"tokenBudget": 8192
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"cortex-mcp": {
|
|
35
|
+
"command": "npx",
|
|
36
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
37
|
+
}
|
|
145
38
|
}
|
|
146
39
|
}
|
|
147
40
|
```
|
|
148
41
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
| URI Pattern | Description | MIME Type |
|
|
152
|
-
| :----------------------------------------------------- | :------------------------------------------------- | :----------------- |
|
|
153
|
-
| `internal://instructions` | Usage instructions for the MCP server. | `text/markdown` |
|
|
154
|
-
| `reasoning://sessions` | List of active reasoning sessions. | `application/json` |
|
|
155
|
-
| `reasoning://sessions/{sessionId}` | Detailed view of a reasoning session. | `application/json` |
|
|
156
|
-
| `file:///cortex/sessions/{sessionId}/trace.md` | Full Markdown trace of a session. | `text/markdown` |
|
|
157
|
-
| `file:///cortex/sessions/{sessionId}/{thoughtName}.md` | Content of a single thought (e.g. `Thought-1.md`). | `text/markdown` |
|
|
158
|
-
|
|
159
|
-
### Prompts
|
|
160
|
-
|
|
161
|
-
| Name | Arguments | Description |
|
|
162
|
-
| :------------------- | :--------------------------------- | :-------------------------------------------- |
|
|
163
|
-
| `reasoning.basic` | `query`, `targetThoughts` | Prepare a basic-depth reasoning request. |
|
|
164
|
-
| `reasoning.normal` | `query`, `targetThoughts` | Prepare a normal-depth reasoning request. |
|
|
165
|
-
| `reasoning.high` | `query`, `targetThoughts` | Prepare a high-depth reasoning request. |
|
|
166
|
-
| `reasoning.retry` | `query`, `level`, `targetThoughts` | Retry a failed task with modified parameters. |
|
|
167
|
-
| `reasoning.continue` | `sessionId`, `query`, `level`, ... | Continue an existing session. |
|
|
168
|
-
| `get-help` | - | Return server usage instructions. |
|
|
169
|
-
|
|
170
|
-
### Tasks
|
|
171
|
-
|
|
172
|
-
This server supports **async task execution** for `reasoning.think`.
|
|
42
|
+
> [!TIP]
|
|
43
|
+
> Use the standard config first, then add per-client configuration below if needed.
|
|
173
44
|
|
|
174
|
-
|
|
175
|
-
- **Usage**: Clients can invoke the tool as a background task.
|
|
176
|
-
- **Monitoring**: Progress is reported via `notifications/progress` (on 'high' level, typically every 2 steps).
|
|
177
|
-
|
|
178
|
-
## Client Configuration Examples
|
|
45
|
+
## Client Configuration
|
|
179
46
|
|
|
180
47
|
<details>
|
|
181
|
-
<summary><
|
|
48
|
+
<summary><b>Install in VS Code</b></summary>
|
|
49
|
+
|
|
50
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=cortex-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcortex-mcp%40latest%22%5D%7D)
|
|
182
51
|
|
|
183
|
-
Add to your `settings.json`:
|
|
52
|
+
Add to your user `settings.json`:
|
|
184
53
|
|
|
185
54
|
```json
|
|
186
55
|
{
|
|
@@ -188,173 +57,207 @@ Add to your `settings.json`:
|
|
|
188
57
|
"servers": {
|
|
189
58
|
"cortex-mcp": {
|
|
190
59
|
"command": "npx",
|
|
191
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
60
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
192
61
|
}
|
|
193
62
|
}
|
|
194
63
|
}
|
|
195
64
|
}
|
|
196
65
|
```
|
|
197
66
|
|
|
67
|
+
> [!NOTE]
|
|
68
|
+
> Missing info: official VS Code MCP docs URL is not referenced in this repo.
|
|
69
|
+
|
|
198
70
|
</details>
|
|
199
71
|
|
|
200
72
|
<details>
|
|
201
|
-
<summary><
|
|
73
|
+
<summary><b>Install in VS Code Insiders</b></summary>
|
|
74
|
+
|
|
75
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=cortex-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcortex-mcp%40latest%22%5D%7D&quality=insiders)
|
|
202
76
|
|
|
203
|
-
Add to your `
|
|
77
|
+
Add to your user `settings.json`:
|
|
204
78
|
|
|
205
79
|
```json
|
|
206
80
|
{
|
|
207
|
-
"
|
|
208
|
-
"
|
|
209
|
-
"
|
|
210
|
-
|
|
81
|
+
"mcp": {
|
|
82
|
+
"servers": {
|
|
83
|
+
"cortex-mcp": {
|
|
84
|
+
"command": "npx",
|
|
85
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
86
|
+
}
|
|
211
87
|
}
|
|
212
88
|
}
|
|
213
89
|
}
|
|
214
90
|
```
|
|
215
91
|
|
|
92
|
+
> [!NOTE]
|
|
93
|
+
> Missing info: official VS Code Insiders MCP docs URL is not referenced in this repo.
|
|
94
|
+
|
|
216
95
|
</details>
|
|
217
96
|
|
|
218
97
|
<details>
|
|
219
|
-
<summary><
|
|
98
|
+
<summary><b>Install in Cursor</b></summary>
|
|
99
|
+
|
|
100
|
+
[](https://cursor.com/en/install-mcp?name=cortex-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29ydGV4LW1jcEBsYXRlc3QiXX0=)
|
|
220
101
|
|
|
221
|
-
Add to
|
|
102
|
+
Add to `~/.cursor/mcp.json`:
|
|
222
103
|
|
|
223
104
|
```json
|
|
224
105
|
{
|
|
225
106
|
"mcpServers": {
|
|
226
107
|
"cortex-mcp": {
|
|
227
108
|
"command": "npx",
|
|
228
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
109
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
229
110
|
}
|
|
230
111
|
}
|
|
231
112
|
}
|
|
232
113
|
```
|
|
233
114
|
|
|
115
|
+
> [!NOTE]
|
|
116
|
+
> Missing info: official Cursor MCP docs URL is not referenced in this repo.
|
|
117
|
+
|
|
234
118
|
</details>
|
|
235
119
|
|
|
236
120
|
<details>
|
|
237
|
-
<summary><
|
|
121
|
+
<summary><b>Install in Claude Desktop</b></summary>
|
|
122
|
+
|
|
123
|
+
Add to `claude_desktop_config.json`:
|
|
238
124
|
|
|
239
125
|
```json
|
|
240
126
|
{
|
|
241
127
|
"mcpServers": {
|
|
242
128
|
"cortex-mcp": {
|
|
243
|
-
"command": "
|
|
244
|
-
"args": ["
|
|
129
|
+
"command": "npx",
|
|
130
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
245
131
|
}
|
|
246
132
|
}
|
|
247
133
|
}
|
|
248
134
|
```
|
|
249
135
|
|
|
250
|
-
|
|
136
|
+
> [!NOTE]
|
|
137
|
+
> Missing info: official Claude Desktop MCP docs URL is not referenced in this repo.
|
|
251
138
|
|
|
252
|
-
|
|
139
|
+
</details>
|
|
253
140
|
|
|
254
|
-
|
|
255
|
-
- **Input Validation**: All tool inputs conform to strict Zod schemas with character limits (`max(10000)` for queries).
|
|
256
|
-
- **Filesystem**: No actual filesystem writes occur; "files" are exposed virtually via resources.
|
|
141
|
+
## MCP Surface
|
|
257
142
|
|
|
258
|
-
|
|
143
|
+
### Tools
|
|
259
144
|
|
|
260
|
-
|
|
145
|
+
#### reasoning.think
|
|
261
146
|
|
|
262
|
-
|
|
263
|
-
npm install
|
|
264
|
-
```
|
|
147
|
+
Perform multi-step reasoning on a query with a selected depth level.
|
|
265
148
|
|
|
266
|
-
|
|
149
|
+
| Name | Type | Required | Default | Description |
|
|
150
|
+
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------- |
|
|
151
|
+
| query | string | Yes | - | The question or problem to reason about (1-10,000 chars). |
|
|
152
|
+
| level | enum | Yes | - | Reasoning depth level: `basic`, `normal`, `high`. |
|
|
153
|
+
| targetThoughts | number | No | - | Optional explicit thought count within the selected level range. |
|
|
154
|
+
| sessionId | string | No | - | Session ID to continue a previous reasoning session. |
|
|
267
155
|
|
|
268
|
-
|
|
269
|
-
| :---------- | :----------------------------- | :------------------------------- |
|
|
270
|
-
| `build` | `node scripts/tasks.mjs build` | Clean, compile, and copy assets. |
|
|
271
|
-
| `dev` | `tsc --watch ...` | Watch mode compilation. |
|
|
272
|
-
| `dev:run` | `node --watch dist/index.js` | Run server with auto-restart. |
|
|
273
|
-
| `test` | `node scripts/tasks.mjs test` | Build and run tests. |
|
|
274
|
-
| `lint` | `eslint .` | Lint source files. |
|
|
275
|
-
| `inspector` | `npm run build && ...` | Launch MCP Inspector. |
|
|
156
|
+
Returns a structured result with session metadata, thoughts, and token usage:
|
|
276
157
|
|
|
277
|
-
|
|
158
|
+
```json
|
|
159
|
+
{
|
|
160
|
+
"ok": true,
|
|
161
|
+
"result": {
|
|
162
|
+
"sessionId": "8e2e2c7a-1234-4567-89ab-001122334455",
|
|
163
|
+
"level": "normal",
|
|
164
|
+
"status": "active",
|
|
165
|
+
"thoughts": [{ "index": 0, "content": "Step 1/6: ...", "revision": 0 }],
|
|
166
|
+
"generatedThoughts": 1,
|
|
167
|
+
"requestedThoughts": 6,
|
|
168
|
+
"totalThoughts": 6,
|
|
169
|
+
"tokenBudget": 8192,
|
|
170
|
+
"tokensUsed": 128,
|
|
171
|
+
"ttlMs": 1800000,
|
|
172
|
+
"expiresAt": 1739356800000,
|
|
173
|
+
"createdAt": 1739356500000,
|
|
174
|
+
"updatedAt": 1739356505000,
|
|
175
|
+
"summary": "Session [8e2e2c7a-1234-4567-89ab-001122334455] at level [normal] with [1] thoughts."
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
278
179
|
|
|
279
|
-
|
|
180
|
+
### Resources
|
|
280
181
|
|
|
281
|
-
|
|
282
|
-
|
|
182
|
+
| URI Pattern | Description | MIME Type |
|
|
183
|
+
| ---------------------------------------------------- | ------------------------------------------------- | ---------------- |
|
|
184
|
+
| internal://instructions | Usage instructions for the MCP server. | text/markdown |
|
|
185
|
+
| reasoning://sessions | List of active reasoning sessions with summaries. | application/json |
|
|
186
|
+
| reasoning://sessions/{sessionId} | Detailed view of a reasoning session. | application/json |
|
|
187
|
+
| file:///cortex/sessions/{sessionId}/trace.md | Markdown trace of a reasoning session. | text/markdown |
|
|
188
|
+
| file:///cortex/sessions/{sessionId}/{thoughtName}.md | Markdown content of a single thought. | text/markdown |
|
|
283
189
|
|
|
284
|
-
###
|
|
190
|
+
### Prompts
|
|
285
191
|
|
|
286
|
-
|
|
192
|
+
| Name | Arguments | Description |
|
|
193
|
+
| ------------------ | --------------------------------------- | ------------------------------------------------------- |
|
|
194
|
+
| reasoning.basic | query, targetThoughts | Prepare a basic-depth reasoning request. |
|
|
195
|
+
| reasoning.normal | query, targetThoughts | Prepare a normal-depth reasoning request. |
|
|
196
|
+
| reasoning.high | query, targetThoughts | Prepare a high-depth reasoning request. |
|
|
197
|
+
| reasoning.retry | query, level, targetThoughts | Retry a failed reasoning task with modified parameters. |
|
|
198
|
+
| reasoning.continue | sessionId, query, level, targetThoughts | Continue an existing reasoning session. |
|
|
199
|
+
| get-help | - | Return server usage instructions. |
|
|
287
200
|
|
|
288
|
-
|
|
201
|
+
### Tasks
|
|
289
202
|
|
|
290
|
-
|
|
291
|
-
# Via GitHub CLI
|
|
292
|
-
gh workflow run release.yml -f bump=patch # or minor / major
|
|
203
|
+
Task-augmented tool calls are supported for `reasoning.think` with `taskSupport: optional`.
|
|
293
204
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
205
|
+
- Call the tool as a task to receive a task id.
|
|
206
|
+
- Poll `tasks/get` and read results via `tasks/result`.
|
|
207
|
+
- Cancel with `tasks/cancel`.
|
|
297
208
|
|
|
298
|
-
|
|
209
|
+
## Configuration
|
|
299
210
|
|
|
300
|
-
|
|
211
|
+
### Runtime Modes
|
|
301
212
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
▼
|
|
306
|
-
release ── bump versions → validate → commit → tag → GitHub Release
|
|
307
|
-
│
|
|
308
|
-
├──► publish-npm ──► publish-mcp (sequential: MCP Registry needs npm package)
|
|
309
|
-
│
|
|
310
|
-
└──► publish-docker (parallel with npm)
|
|
311
|
-
```
|
|
213
|
+
| Mode | Description |
|
|
214
|
+
| ----- | ----------------------------- |
|
|
215
|
+
| stdio | The only supported transport. |
|
|
312
216
|
|
|
313
|
-
|
|
314
|
-
2. **Validate** — Runs lint, type-check, tests, and build
|
|
315
|
-
3. **Tag & Release** — Commits, creates a git tag, and a GitHub Release with auto-generated notes
|
|
316
|
-
4. **Publish to npm** — Uses OIDC Trusted Publishing (no `NPM_TOKEN` secret needed), with `--provenance` for signed SLSA attestations
|
|
317
|
-
5. **Publish to MCP Registry** — Registers the new version via `mcp-publisher` with GitHub OIDC
|
|
318
|
-
6. **Publish to Docker** — Builds and pushes a multi-platform image (`linux/amd64`, `linux/arm64`) to `ghcr.io/j0hanz/cortex-mcp`
|
|
217
|
+
### Environment Variables
|
|
319
218
|
|
|
320
|
-
|
|
219
|
+
> [!NOTE]
|
|
220
|
+
> Missing info: no environment variables are documented in this repo.
|
|
321
221
|
|
|
322
|
-
|
|
222
|
+
## Development
|
|
323
223
|
|
|
324
|
-
|
|
325
|
-
- **Release stage**: Minimal `node:24-alpine` image running as non-root `mcp` user
|
|
224
|
+
Install dependencies:
|
|
326
225
|
|
|
327
226
|
```bash
|
|
328
|
-
|
|
329
|
-
|
|
227
|
+
npm install
|
|
228
|
+
```
|
|
330
229
|
|
|
331
|
-
|
|
332
|
-
docker run --rm -i cortex-mcp
|
|
230
|
+
Scripts:
|
|
333
231
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
232
|
+
| Script | Command | Purpose |
|
|
233
|
+
| ---------- | --------------------------------------------------------------------------------------------- | --------------------------------------- |
|
|
234
|
+
| clean | node scripts/tasks.mjs clean | Remove build artifacts. |
|
|
235
|
+
| build | node scripts/tasks.mjs build | Build the server to dist/. |
|
|
236
|
+
| dev | tsc --watch --preserveWatchOutput | Watch and compile TypeScript. |
|
|
237
|
+
| dev:run | node --env-file=.env --watch dist/index.js | Run the built server with auto-restart. |
|
|
238
|
+
| format | prettier --write . | Format the codebase. |
|
|
239
|
+
| type-check | node scripts/tasks.mjs type-check | Run TypeScript type checks. |
|
|
240
|
+
| lint | eslint . | Lint the codebase. |
|
|
241
|
+
| test | node scripts/tasks.mjs test | Build and run tests. |
|
|
242
|
+
| inspector | npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder} | Launch MCP Inspector. |
|
|
337
243
|
|
|
338
|
-
|
|
244
|
+
Debug with MCP Inspector:
|
|
339
245
|
|
|
340
246
|
```bash
|
|
341
|
-
|
|
342
|
-
|
|
247
|
+
npx @modelcontextprotocol/inspector node dist/index.js
|
|
248
|
+
```
|
|
343
249
|
|
|
344
|
-
|
|
345
|
-
docker pull ghcr.io/j0hanz/cortex-mcp:latest
|
|
250
|
+
## Build and Release
|
|
346
251
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
| head -1 | jq .result.serverInfo
|
|
351
|
-
```
|
|
252
|
+
The GitHub Actions workflow in `.github/workflows/release.yml` automates version bumps, testing, publishing to npm, MCP Registry, and Docker image publishing.
|
|
253
|
+
|
|
254
|
+
Docker support is included via the multi-stage `Dockerfile` and `docker-compose.yml`.
|
|
352
255
|
|
|
353
256
|
## Troubleshooting
|
|
354
257
|
|
|
355
|
-
-
|
|
356
|
-
-
|
|
357
|
-
-
|
|
258
|
+
- If your client shows no output, remember this is a stdio server and the JSON-RPC stream is on stdout.
|
|
259
|
+
- Use `npm run inspector` to explore tools, resources, and prompts.
|
|
260
|
+
- Sessions are in-memory and expire after 30 minutes of inactivity.
|
|
358
261
|
|
|
359
262
|
## License
|
|
360
263
|
|
package/dist/engine/config.d.ts
CHANGED
|
@@ -1,9 +1,4 @@
|
|
|
1
1
|
import type { LevelConfig, ReasoningLevel } from '../lib/types.js';
|
|
2
2
|
export declare const LEVEL_CONFIGS: Record<ReasoningLevel, LevelConfig>;
|
|
3
|
-
export declare function getThoughtBounds(level: ReasoningLevel): {
|
|
4
|
-
minThoughts: number;
|
|
5
|
-
maxThoughts: number;
|
|
6
|
-
};
|
|
7
|
-
export declare function getTargetThoughtsError(level: ReasoningLevel, targetThoughts: number): string | undefined;
|
|
8
3
|
export declare function assertTargetThoughtsInRange(level: ReasoningLevel, targetThoughts: number): void;
|
|
9
4
|
//# sourceMappingURL=config.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/engine/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/engine/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGnE,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,cAAc,EAAE,WAAW,CAI7D,CAAC;AAEF,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,cAAc,EACrB,cAAc,EAAE,MAAM,GACrB,IAAI,CAKN"}
|
package/dist/engine/config.js
CHANGED
|
@@ -1,22 +1,9 @@
|
|
|
1
|
+
import { getTargetThoughtsError } from '../lib/validators.js';
|
|
1
2
|
export const LEVEL_CONFIGS = {
|
|
2
3
|
basic: { minThoughts: 3, maxThoughts: 5, tokenBudget: 2048 },
|
|
3
4
|
normal: { minThoughts: 6, maxThoughts: 10, tokenBudget: 8192 },
|
|
4
5
|
high: { minThoughts: 15, maxThoughts: 25, tokenBudget: 32768 },
|
|
5
6
|
};
|
|
6
|
-
export function getThoughtBounds(level) {
|
|
7
|
-
const { minThoughts, maxThoughts } = LEVEL_CONFIGS[level];
|
|
8
|
-
return { minThoughts, maxThoughts };
|
|
9
|
-
}
|
|
10
|
-
export function getTargetThoughtsError(level, targetThoughts) {
|
|
11
|
-
if (!Number.isInteger(targetThoughts)) {
|
|
12
|
-
return 'targetThoughts must be an integer';
|
|
13
|
-
}
|
|
14
|
-
const { minThoughts, maxThoughts } = getThoughtBounds(level);
|
|
15
|
-
if (targetThoughts < minThoughts || targetThoughts > maxThoughts) {
|
|
16
|
-
return `targetThoughts must be between ${String(minThoughts)} and ${String(maxThoughts)} for the selected level`;
|
|
17
|
-
}
|
|
18
|
-
return undefined;
|
|
19
|
-
}
|
|
20
7
|
export function assertTargetThoughtsInRange(level, targetThoughts) {
|
|
21
8
|
const error = getTargetThoughtsError(level, targetThoughts);
|
|
22
9
|
if (error) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/engine/config.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/engine/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,CAAC,MAAM,aAAa,GAAwC;IAChE,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE;IAC5D,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;IAC9D,IAAI,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;CAC/D,CAAC;AAEF,MAAM,UAAU,2BAA2B,CACzC,KAAqB,EACrB,cAAsB;IAEtB,MAAM,KAAK,GAAG,sBAAsB,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IAC5D,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}
|
package/dist/engine/events.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,UAAU,YAAY;IACpB,eAAe,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE,iBAAiB,EAAE;QACjB;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE;KACxE,CAAC;IACF,0BAA0B,EAAE;QAC1B;YACE,SAAS,EAAE,MAAM,CAAC;YAClB,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;YACpB,iBAAiB,EAAE,MAAM,CAAC;YAC1B,iBAAiB,EAAE,MAAM,CAAC;SAC3B;KACF,CAAC;IACF,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAClE,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,mBAAmB,EAAE,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvC,kBAAkB,EAAE,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;CAClB;AAED,UAAU,YAAY,CAAC,CAAC,CAAE,SAAQ,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;IACzE,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAClB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,GACjE,IAAI,CAAC;IACR,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EACnB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,GACjE,IAAI,CAAC;IACR,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,EACpB,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAC7C,OAAO,CAAC;CACZ;AAED,eAAO,MAAM,YAAY,EAEnB,YAAY,CAAC,YAAY,CAAC,CAAC"}
|
|
1
|
+
{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,UAAU,YAAY;IACpB,eAAe,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE,iBAAiB,EAAE;QACjB;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE;KACxE,CAAC;IACF,0BAA0B,EAAE;QAC1B;YACE,SAAS,EAAE,MAAM,CAAC;YAClB,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;YACpB,iBAAiB,EAAE,MAAM,CAAC;YAC1B,iBAAiB,EAAE,MAAM,CAAC;SAC3B;KACF,CAAC;IACF,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAClE,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,iBAAiB,EAAE,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,mBAAmB,EAAE,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvC,kBAAkB,EAAE,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;CAClB;AAED,UAAU,YAAY,CAAC,CAAC,CAAE,SAAQ,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;IACzE,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAClB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,GACjE,IAAI,CAAC;IACR,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EACnB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,GACjE,IAAI,CAAC;IACR,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,EACpB,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAC7C,OAAO,CAAC;CACZ;AAED,eAAO,MAAM,YAAY,EAEnB,YAAY,CAAC,YAAY,CAAC,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAyCnD,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC;IAC3C,iBAAiB,EAAE,IAAI;CACxB,CAA+B,CAAC;AAEjC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC,CAAC,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"reasoner.d.ts","sourceRoot":"","sources":["../../src/engine/reasoner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK/D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,QAAA,MAAM,YAAY,cAAqB,CAAC;AAMxC,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,UAAU,aAAa;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAQD,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,
|
|
1
|
+
{"version":3,"file":"reasoner.d.ts","sourceRoot":"","sources":["../../src/engine/reasoner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK/D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,QAAA,MAAM,YAAY,cAAqB,CAAC;AAMxC,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,UAAU,aAAa;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAQD,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CA+E5B"}
|