@j0hanz/cortex-mcp 1.0.0 → 1.1.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.
- package/README.md +143 -245
- package/dist/engine/config.d.ts +17 -6
- 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 +1 -0
- package/dist/engine/reasoner.d.ts.map +1 -1
- package/dist/engine/reasoner.js +31 -61
- package/dist/engine/reasoner.js.map +1 -1
- package/dist/engine/session-store.d.ts +26 -3
- package/dist/engine/session-store.d.ts.map +1 -1
- package/dist/engine/session-store.js +267 -26
- package/dist/engine/session-store.js.map +1 -1
- package/dist/instructions.md +33 -13
- 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 +14 -11
- 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.d.ts.map +1 -1
- package/dist/prompts/index.js +32 -9
- package/dist/prompts/index.js.map +1 -1
- package/dist/resources/index.d.ts.map +1 -1
- package/dist/resources/index.js +83 -19
- package/dist/resources/index.js.map +1 -1
- package/dist/schemas/inputs.d.ts +7 -1
- package/dist/schemas/inputs.d.ts.map +1 -1
- package/dist/schemas/inputs.js +42 -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 +268 -71
- 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,52 @@
|
|
|
1
1
|
# Cortex MCP
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@j0hanz/cortex-mcp) [](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)
|
|
4
4
|
|
|
5
|
-
[](vscode
|
|
5
|
+
[](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)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[](https://cursor.com/en/install-mcp?name=cortex-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29ydGV4LW1jcEBsYXRlc3QiXX0=)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Multi-level reasoning MCP server with configurable depth levels.
|
|
10
10
|
|
|
11
|
-
Cortex MCP
|
|
11
|
+
Cortex MCP exposes a single `reasoning.think` tool over stdio, providing structured reasoning with session continuity, resource views, prompt/resource completions, and task execution for multi-step runs.
|
|
12
12
|
|
|
13
13
|
## Key Features
|
|
14
14
|
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
## Tech Stack
|
|
23
|
-
|
|
24
|
-
- **Runtime**: Node.js >= 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
|
|
30
|
-
|
|
31
|
-
## Architecture
|
|
32
|
-
|
|
33
|
-
1. **Transport**: Receives JSON-RPC messages via `stdio`.
|
|
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.
|
|
38
|
-
|
|
39
|
-
## Repository Structure
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
cortex-mcp/
|
|
43
|
-
├── src/
|
|
44
|
-
│ ├── index.ts # CLI entry point (stdio transport)
|
|
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
|
-
```
|
|
15
|
+
- Multi-level reasoning (`basic`, `normal`, `high`) with configurable thought counts and token budgets.
|
|
16
|
+
- Optional task execution with progress notifications for multi-step requests.
|
|
17
|
+
- Dual execution modes: `step` (single thought) and `run_to_completion` (batched thoughts).
|
|
18
|
+
- Resource endpoints for session lists, session detail, markdown traces, and thought files.
|
|
19
|
+
- Prompt/resource argument completion for session IDs, levels, and thought names.
|
|
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
|
-
```
|
|
76
|
-
|
|
77
|
-
### Docker
|
|
78
|
-
|
|
79
|
-
```bash
|
|
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
|
|
24
|
+
- Node.js >= 24
|
|
25
|
+
- An MCP client that supports stdio servers
|
|
115
26
|
|
|
116
|
-
|
|
27
|
+
## Quick Start
|
|
117
28
|
|
|
118
|
-
|
|
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`.
|
|
173
|
-
|
|
174
|
-
- **Capability**: `execution: { taskSupport: 'optional' }`
|
|
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
|
|
42
|
+
## Client Configuration
|
|
179
43
|
|
|
180
44
|
<details>
|
|
181
|
-
<summary><
|
|
45
|
+
<summary><b>Install in VS Code</b></summary>
|
|
46
|
+
|
|
47
|
+
[](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
48
|
|
|
183
|
-
Add to your `settings.json`:
|
|
49
|
+
Add to your user `settings.json`:
|
|
184
50
|
|
|
185
51
|
```json
|
|
186
52
|
{
|
|
@@ -188,7 +54,7 @@ Add to your `settings.json`:
|
|
|
188
54
|
"servers": {
|
|
189
55
|
"cortex-mcp": {
|
|
190
56
|
"command": "npx",
|
|
191
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
57
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
192
58
|
}
|
|
193
59
|
}
|
|
194
60
|
}
|
|
@@ -198,16 +64,20 @@ Add to your `settings.json`:
|
|
|
198
64
|
</details>
|
|
199
65
|
|
|
200
66
|
<details>
|
|
201
|
-
<summary><
|
|
67
|
+
<summary><b>Install in VS Code Insiders</b></summary>
|
|
202
68
|
|
|
203
|
-
|
|
69
|
+
[](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)
|
|
70
|
+
|
|
71
|
+
Add to your user `settings.json`:
|
|
204
72
|
|
|
205
73
|
```json
|
|
206
74
|
{
|
|
207
|
-
"
|
|
208
|
-
"
|
|
209
|
-
"
|
|
210
|
-
|
|
75
|
+
"mcp": {
|
|
76
|
+
"servers": {
|
|
77
|
+
"cortex-mcp": {
|
|
78
|
+
"command": "npx",
|
|
79
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
80
|
+
}
|
|
211
81
|
}
|
|
212
82
|
}
|
|
213
83
|
}
|
|
@@ -216,16 +86,18 @@ Add to your `claude_desktop_config.json`:
|
|
|
216
86
|
</details>
|
|
217
87
|
|
|
218
88
|
<details>
|
|
219
|
-
<summary><
|
|
89
|
+
<summary><b>Install in Cursor</b></summary>
|
|
90
|
+
|
|
91
|
+
[](https://cursor.com/en/install-mcp?name=cortex-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29ydGV4LW1jcEBsYXRlc3QiXX0=)
|
|
220
92
|
|
|
221
|
-
Add to
|
|
93
|
+
Add to `~/.cursor/mcp.json`:
|
|
222
94
|
|
|
223
95
|
```json
|
|
224
96
|
{
|
|
225
97
|
"mcpServers": {
|
|
226
98
|
"cortex-mcp": {
|
|
227
99
|
"command": "npx",
|
|
228
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
100
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
229
101
|
}
|
|
230
102
|
}
|
|
231
103
|
}
|
|
@@ -234,14 +106,16 @@ Add to your Cursor MCP settings:
|
|
|
234
106
|
</details>
|
|
235
107
|
|
|
236
108
|
<details>
|
|
237
|
-
<summary><
|
|
109
|
+
<summary><b>Install in Claude Desktop</b></summary>
|
|
110
|
+
|
|
111
|
+
Add to `claude_desktop_config.json`:
|
|
238
112
|
|
|
239
113
|
```json
|
|
240
114
|
{
|
|
241
115
|
"mcpServers": {
|
|
242
116
|
"cortex-mcp": {
|
|
243
|
-
"command": "
|
|
244
|
-
"args": ["
|
|
117
|
+
"command": "npx",
|
|
118
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
245
119
|
}
|
|
246
120
|
}
|
|
247
121
|
}
|
|
@@ -249,112 +123,136 @@ Add to your Cursor MCP settings:
|
|
|
249
123
|
|
|
250
124
|
</details>
|
|
251
125
|
|
|
252
|
-
##
|
|
126
|
+
## MCP Surface
|
|
253
127
|
|
|
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.
|
|
128
|
+
### Tools
|
|
257
129
|
|
|
258
|
-
|
|
130
|
+
#### reasoning.think
|
|
259
131
|
|
|
260
|
-
|
|
132
|
+
Perform multi-step reasoning on a query with a selected depth level.
|
|
261
133
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
134
|
+
| Name | Type | Required | Default | Description |
|
|
135
|
+
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------- |
|
|
136
|
+
| query | string | No | - | Required for new sessions; optional when `sessionId` is provided. |
|
|
137
|
+
| level | enum | Yes | - | Reasoning depth level: `basic`, `normal`, `high`. |
|
|
138
|
+
| runMode | enum | No | `step` | `step` appends one thought; `run_to_completion` consumes `thought` + `thoughts[]`. |
|
|
139
|
+
| thought | string | Yes | - | Reasoning content for the next step (stored verbatim). |
|
|
140
|
+
| thoughts | array | No | - | Additional thought inputs consumed in order when `runMode=run_to_completion`. |
|
|
141
|
+
| targetThoughts | number | No | - | Optional explicit thought count within the selected level range. |
|
|
142
|
+
| sessionId | string | No | - | Session ID to continue a previous reasoning session. |
|
|
265
143
|
|
|
266
|
-
|
|
144
|
+
Returns a structured result with session metadata, thoughts, and token usage:
|
|
267
145
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"ok": true,
|
|
149
|
+
"result": {
|
|
150
|
+
"sessionId": "8e2e2c7a-1234-4567-89ab-001122334455",
|
|
151
|
+
"level": "normal",
|
|
152
|
+
"status": "active",
|
|
153
|
+
"thoughts": [{ "index": 0, "content": "Step 1/6: ...", "revision": 0 }],
|
|
154
|
+
"generatedThoughts": 1,
|
|
155
|
+
"requestedThoughts": 6,
|
|
156
|
+
"totalThoughts": 6,
|
|
157
|
+
"tokenBudget": 8192,
|
|
158
|
+
"tokensUsed": 128,
|
|
159
|
+
"ttlMs": 1800000,
|
|
160
|
+
"expiresAt": 1739356800000,
|
|
161
|
+
"createdAt": 1739356500000,
|
|
162
|
+
"updatedAt": 1739356505000,
|
|
163
|
+
"summary": "Session [8e2e2c7a-1234-4567-89ab-001122334455] at level [normal] with [1] thoughts."
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
276
167
|
|
|
277
|
-
|
|
168
|
+
### Resources
|
|
278
169
|
|
|
279
|
-
|
|
170
|
+
| URI Pattern | Description | MIME Type |
|
|
171
|
+
| ---------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------- |
|
|
172
|
+
| internal://instructions | Usage instructions for the MCP server. | text/markdown |
|
|
173
|
+
| reasoning://sessions | List of active reasoning sessions with summaries. | application/json |
|
|
174
|
+
| reasoning://sessions/{sessionId} | Detailed view of a reasoning session. | application/json |
|
|
175
|
+
| file:///cortex/sessions/{sessionId}/trace.md | Markdown trace of a reasoning session (`sessionId` completion). | text/markdown |
|
|
176
|
+
| file:///cortex/sessions/{sessionId}/{thoughtName}.md | Markdown content of a single thought (`sessionId` + `thoughtName` completion). | text/markdown |
|
|
280
177
|
|
|
281
|
-
|
|
282
|
-
- **Publish**: `npm run prepublishOnly` ensures linting, type-checking, and building before publish.
|
|
178
|
+
### Prompts
|
|
283
179
|
|
|
284
|
-
|
|
180
|
+
| Name | Arguments | Description |
|
|
181
|
+
| ------------------ | ---------------------------------------- | ------------------------------------------------------- |
|
|
182
|
+
| reasoning.basic | query, targetThoughts | Prepare a basic-depth reasoning request. |
|
|
183
|
+
| reasoning.normal | query, targetThoughts | Prepare a normal-depth reasoning request. |
|
|
184
|
+
| reasoning.high | query, targetThoughts | Prepare a high-depth reasoning request. |
|
|
185
|
+
| reasoning.retry | query, level, targetThoughts | Retry a failed reasoning task with modified parameters. |
|
|
186
|
+
| reasoning.continue | sessionId, query?, level, targetThoughts | Continue an existing reasoning session. |
|
|
187
|
+
| get-help | - | Return server usage instructions. |
|
|
285
188
|
|
|
286
|
-
|
|
189
|
+
### Tasks
|
|
287
190
|
|
|
288
|
-
|
|
191
|
+
Task-augmented tool calls are supported for `reasoning.think` with `taskSupport: optional`.
|
|
289
192
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
193
|
+
- Call the tool as a task to receive a task id.
|
|
194
|
+
- Poll `tasks/get` and read results via `tasks/result`.
|
|
195
|
+
- Cancel with `tasks/cancel`.
|
|
196
|
+
- Use `runMode: "run_to_completion"` to consume multiple thought inputs in one task.
|
|
293
197
|
|
|
294
|
-
|
|
295
|
-
gh workflow run release.yml -f custom_version=2.0.0-beta.1
|
|
296
|
-
```
|
|
198
|
+
## Configuration
|
|
297
199
|
|
|
298
|
-
|
|
200
|
+
### Runtime Modes
|
|
299
201
|
|
|
300
|
-
|
|
202
|
+
| Mode | Description |
|
|
203
|
+
| ----- | ----------------------------- |
|
|
204
|
+
| stdio | The only supported transport. |
|
|
301
205
|
|
|
302
|
-
|
|
303
|
-
workflow_dispatch (patch/minor/major)
|
|
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
|
-
```
|
|
206
|
+
### Session Store Limits
|
|
312
207
|
|
|
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`
|
|
208
|
+
Environment variables:
|
|
319
209
|
|
|
320
|
-
|
|
210
|
+
| Variable | Default | Description |
|
|
211
|
+
| ----------------------------------- | --------- | -------------------------------------------------------------- |
|
|
212
|
+
| `CORTEX_SESSION_TTL_MS` | `1800000` | Session TTL in milliseconds. |
|
|
213
|
+
| `CORTEX_MAX_SESSIONS` | `100` | Maximum in-memory sessions before LRU-style eviction. |
|
|
214
|
+
| `CORTEX_MAX_TOTAL_TOKENS` | `500000` | Maximum aggregate approximate token footprint across sessions. |
|
|
215
|
+
| `CORTEX_MAX_ACTIVE_REASONING_TASKS` | `32` | Maximum concurrently running background reasoning tasks. |
|
|
321
216
|
|
|
322
|
-
|
|
217
|
+
## Development
|
|
323
218
|
|
|
324
|
-
|
|
325
|
-
- **Release stage**: Minimal `node:24-alpine` image running as non-root `mcp` user
|
|
219
|
+
Install dependencies:
|
|
326
220
|
|
|
327
221
|
```bash
|
|
328
|
-
|
|
329
|
-
|
|
222
|
+
npm install
|
|
223
|
+
```
|
|
330
224
|
|
|
331
|
-
|
|
332
|
-
docker run --rm -i cortex-mcp
|
|
225
|
+
Scripts:
|
|
333
226
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
227
|
+
| Script | Command | Purpose |
|
|
228
|
+
| ---------- | --------------------------------------------------------------------------------------------- | --------------------------------------- |
|
|
229
|
+
| clean | node scripts/tasks.mjs clean | Remove build artifacts. |
|
|
230
|
+
| build | node scripts/tasks.mjs build | Build the server to dist/. |
|
|
231
|
+
| dev | tsc --watch --preserveWatchOutput | Watch and compile TypeScript. |
|
|
232
|
+
| dev:run | node --env-file=.env --watch dist/index.js | Run the built server with auto-restart. |
|
|
233
|
+
| format | prettier --write . | Format the codebase. |
|
|
234
|
+
| type-check | node scripts/tasks.mjs type-check | Run TypeScript type checks. |
|
|
235
|
+
| lint | eslint . | Lint the codebase. |
|
|
236
|
+
| test | node scripts/tasks.mjs test | Build and run tests. |
|
|
237
|
+
| inspector | npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder} | Launch MCP Inspector. |
|
|
337
238
|
|
|
338
|
-
|
|
239
|
+
Debug with MCP Inspector:
|
|
339
240
|
|
|
340
241
|
```bash
|
|
341
|
-
|
|
342
|
-
|
|
242
|
+
npx @modelcontextprotocol/inspector node dist/index.js
|
|
243
|
+
```
|
|
343
244
|
|
|
344
|
-
|
|
345
|
-
docker pull ghcr.io/j0hanz/cortex-mcp:latest
|
|
245
|
+
## Build and Release
|
|
346
246
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
| head -1 | jq .result.serverInfo
|
|
351
|
-
```
|
|
247
|
+
The GitHub Actions workflow in `.github/workflows/release.yml` automates version bumps, testing, publishing to npm, MCP Registry, and Docker image publishing.
|
|
248
|
+
|
|
249
|
+
Docker support is included via the multi-stage `Dockerfile` and `docker-compose.yml`.
|
|
352
250
|
|
|
353
251
|
## Troubleshooting
|
|
354
252
|
|
|
355
|
-
-
|
|
356
|
-
-
|
|
357
|
-
-
|
|
253
|
+
- If your client shows no output, remember this is a stdio server and the JSON-RPC stream is on stdout.
|
|
254
|
+
- Use `npm run inspector` to explore tools, resources, and prompts.
|
|
255
|
+
- Sessions are in-memory and expire after 30 minutes of inactivity.
|
|
358
256
|
|
|
359
257
|
## License
|
|
360
258
|
|
package/dist/engine/config.d.ts
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
export declare const LEVEL_CONFIGS:
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
import type { ReasoningLevel } from '../lib/types.js';
|
|
2
|
+
export declare const LEVEL_CONFIGS: {
|
|
3
|
+
readonly basic: {
|
|
4
|
+
readonly minThoughts: 3;
|
|
5
|
+
readonly maxThoughts: 5;
|
|
6
|
+
readonly tokenBudget: 2048;
|
|
7
|
+
};
|
|
8
|
+
readonly normal: {
|
|
9
|
+
readonly minThoughts: 6;
|
|
10
|
+
readonly maxThoughts: 10;
|
|
11
|
+
readonly tokenBudget: 8192;
|
|
12
|
+
};
|
|
13
|
+
readonly high: {
|
|
14
|
+
readonly minThoughts: 15;
|
|
15
|
+
readonly maxThoughts: 25;
|
|
16
|
+
readonly tokenBudget: 32768;
|
|
17
|
+
};
|
|
6
18
|
};
|
|
7
|
-
export declare function getTargetThoughtsError(level: ReasoningLevel, targetThoughts: number): string | undefined;
|
|
8
19
|
export declare function assertTargetThoughtsInRange(level: ReasoningLevel, targetThoughts: number): void;
|
|
9
20
|
//# 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,
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/engine/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGnE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;CAI8B,CAAC;AAEzD,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,GAAG;IAC3B,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;CACR,CAAC;AAEzD,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;
|
|
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;AAsBlD,QAAA,MAAM,YAAY,cAIjB,CAAC;AAKF,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,UAAU,aAAa;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,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,CAwE5B"}
|