@j0hanz/cortex-mcp 0.1.3 → 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 +170 -175
- 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,179 +1,80 @@
|
|
|
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
|
-
```
|
|
24
|
+
- Node.js >= 24
|
|
25
|
+
- An MCP client that supports stdio servers
|
|
68
26
|
|
|
69
|
-
##
|
|
27
|
+
## Quick Start
|
|
70
28
|
|
|
71
|
-
|
|
29
|
+
Standard config (works in most MCP clients):
|
|
72
30
|
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
npm install
|
|
83
|
-
npm run build
|
|
84
|
-
node dist/index.js
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"cortex-mcp": {
|
|
35
|
+
"command": "npx",
|
|
36
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
85
40
|
```
|
|
86
41
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
### Environment Variables
|
|
90
|
-
|
|
91
|
-
No environment variables are strictly required for basic operation.
|
|
92
|
-
|
|
93
|
-
### Runtime Levels
|
|
94
|
-
|
|
95
|
-
The server is configured with the following reasoning levels (defined in `src/engine/config.ts`):
|
|
96
|
-
|
|
97
|
-
| Level | Token Budget | Thoughts Range |
|
|
98
|
-
| :------- | :----------- | :------------- |
|
|
99
|
-
| `basic` | 2,048 | 3–5 |
|
|
100
|
-
| `normal` | 8,192 | 6–10 |
|
|
101
|
-
| `high` | 32,768 | 15–25 |
|
|
102
|
-
|
|
103
|
-
## Usage
|
|
104
|
-
|
|
105
|
-
Configure your MCP client to start the server via stdio.
|
|
106
|
-
|
|
107
|
-
### Stdio Transport
|
|
108
|
-
|
|
109
|
-
Run the server process directly. Messages are sent over `stdin` and `stdout`.
|
|
110
|
-
|
|
111
|
-
## MCP Surface
|
|
112
|
-
|
|
113
|
-
### Tools
|
|
42
|
+
> [!TIP]
|
|
43
|
+
> Use the standard config first, then add per-client configuration below if needed.
|
|
114
44
|
|
|
115
|
-
|
|
45
|
+
## Client Configuration
|
|
116
46
|
|
|
117
|
-
|
|
47
|
+
<details>
|
|
48
|
+
<summary><b>Install in VS Code</b></summary>
|
|
118
49
|
|
|
119
|
-
|
|
120
|
-
| :--------------- | :----- | :------- | :------ | :---------------------------------------------------------- |
|
|
121
|
-
| `query` | string | Yes | - | The question or problem to reason about (max 10,000 chars). |
|
|
122
|
-
| `level` | enum | Yes | - | Depth level: `basic`, `normal`, `high`. |
|
|
123
|
-
| `targetThoughts` | number | No | - | Optional exact step count (max 25). |
|
|
124
|
-
| `sessionId` | string | No | - | Session ID to continue a previous reasoning session. |
|
|
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)
|
|
125
51
|
|
|
126
|
-
|
|
52
|
+
Add to your user `settings.json`:
|
|
127
53
|
|
|
128
54
|
```json
|
|
129
55
|
{
|
|
130
|
-
"
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
"tokenBudget": 8192
|
|
56
|
+
"mcp": {
|
|
57
|
+
"servers": {
|
|
58
|
+
"cortex-mcp": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
61
|
+
}
|
|
62
|
+
}
|
|
138
63
|
}
|
|
139
64
|
}
|
|
140
65
|
```
|
|
141
66
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
| URI Pattern | Description | MIME Type |
|
|
145
|
-
| :----------------------------------------------------- | :------------------------------------------------- | :----------------- |
|
|
146
|
-
| `internal://instructions` | Usage instructions for the MCP server. | `text/markdown` |
|
|
147
|
-
| `reasoning://sessions` | List of active reasoning sessions. | `application/json` |
|
|
148
|
-
| `reasoning://sessions/{sessionId}` | Detailed view of a reasoning session. | `application/json` |
|
|
149
|
-
| `file:///cortex/sessions/{sessionId}/trace.md` | Full Markdown trace of a session. | `text/markdown` |
|
|
150
|
-
| `file:///cortex/sessions/{sessionId}/{thoughtName}.md` | Content of a single thought (e.g. `Thought-1.md`). | `text/markdown` |
|
|
151
|
-
|
|
152
|
-
### Prompts
|
|
153
|
-
|
|
154
|
-
| Name | Arguments | Description |
|
|
155
|
-
| :------------------- | :--------------------------------- | :-------------------------------------------- |
|
|
156
|
-
| `reasoning.basic` | `query`, `targetThoughts` | Prepare a basic-depth reasoning request. |
|
|
157
|
-
| `reasoning.normal` | `query`, `targetThoughts` | Prepare a normal-depth reasoning request. |
|
|
158
|
-
| `reasoning.high` | `query`, `targetThoughts` | Prepare a high-depth reasoning request. |
|
|
159
|
-
| `reasoning.retry` | `query`, `level`, `targetThoughts` | Retry a failed task with modified parameters. |
|
|
160
|
-
| `reasoning.continue` | `sessionId`, `query`, `level`, ... | Continue an existing session. |
|
|
161
|
-
| `get-help` | - | Return server usage instructions. |
|
|
162
|
-
|
|
163
|
-
### Tasks
|
|
67
|
+
> [!NOTE]
|
|
68
|
+
> Missing info: official VS Code MCP docs URL is not referenced in this repo.
|
|
164
69
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
- **Capability**: `execution: { taskSupport: 'optional' }`
|
|
168
|
-
- **Usage**: Clients can invoke the tool as a background task.
|
|
169
|
-
- **Monitoring**: Progress is reported via `notifications/progress` (on 'high' level, typically every 2 steps).
|
|
170
|
-
|
|
171
|
-
## Client Configuration Examples
|
|
70
|
+
</details>
|
|
172
71
|
|
|
173
72
|
<details>
|
|
174
|
-
<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)
|
|
175
76
|
|
|
176
|
-
Add to your `settings.json`:
|
|
77
|
+
Add to your user `settings.json`:
|
|
177
78
|
|
|
178
79
|
```json
|
|
179
80
|
{
|
|
@@ -181,88 +82,182 @@ Add to your `settings.json`:
|
|
|
181
82
|
"servers": {
|
|
182
83
|
"cortex-mcp": {
|
|
183
84
|
"command": "npx",
|
|
184
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
85
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
185
86
|
}
|
|
186
87
|
}
|
|
187
88
|
}
|
|
188
89
|
}
|
|
189
90
|
```
|
|
190
91
|
|
|
92
|
+
> [!NOTE]
|
|
93
|
+
> Missing info: official VS Code Insiders MCP docs URL is not referenced in this repo.
|
|
94
|
+
|
|
191
95
|
</details>
|
|
192
96
|
|
|
193
97
|
<details>
|
|
194
|
-
<summary><
|
|
98
|
+
<summary><b>Install in Cursor</b></summary>
|
|
99
|
+
|
|
100
|
+
[](https://cursor.com/en/install-mcp?name=cortex-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29ydGV4LW1jcEBsYXRlc3QiXX0=)
|
|
195
101
|
|
|
196
|
-
Add to
|
|
102
|
+
Add to `~/.cursor/mcp.json`:
|
|
197
103
|
|
|
198
104
|
```json
|
|
199
105
|
{
|
|
200
106
|
"mcpServers": {
|
|
201
107
|
"cortex-mcp": {
|
|
202
108
|
"command": "npx",
|
|
203
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
109
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
204
110
|
}
|
|
205
111
|
}
|
|
206
112
|
}
|
|
207
113
|
```
|
|
208
114
|
|
|
115
|
+
> [!NOTE]
|
|
116
|
+
> Missing info: official Cursor MCP docs URL is not referenced in this repo.
|
|
117
|
+
|
|
209
118
|
</details>
|
|
210
119
|
|
|
211
120
|
<details>
|
|
212
|
-
<summary><
|
|
121
|
+
<summary><b>Install in Claude Desktop</b></summary>
|
|
213
122
|
|
|
214
|
-
Add to
|
|
123
|
+
Add to `claude_desktop_config.json`:
|
|
215
124
|
|
|
216
125
|
```json
|
|
217
126
|
{
|
|
218
127
|
"mcpServers": {
|
|
219
128
|
"cortex-mcp": {
|
|
220
129
|
"command": "npx",
|
|
221
|
-
"args": ["-y", "cortex-mcp@latest"]
|
|
130
|
+
"args": ["-y", "@j0hanz/cortex-mcp@latest"]
|
|
222
131
|
}
|
|
223
132
|
}
|
|
224
133
|
}
|
|
225
134
|
```
|
|
226
135
|
|
|
136
|
+
> [!NOTE]
|
|
137
|
+
> Missing info: official Claude Desktop MCP docs URL is not referenced in this repo.
|
|
138
|
+
|
|
227
139
|
</details>
|
|
228
140
|
|
|
229
|
-
##
|
|
141
|
+
## MCP Surface
|
|
142
|
+
|
|
143
|
+
### Tools
|
|
230
144
|
|
|
231
|
-
|
|
232
|
-
- **Input Validation**: All tool inputs conform to strict Zod schemas with character limits (`max(10000)` for queries).
|
|
233
|
-
- **Filesystem**: No actual filesystem writes occur; "files" are exposed virtually via resources.
|
|
145
|
+
#### reasoning.think
|
|
234
146
|
|
|
235
|
-
|
|
147
|
+
Perform multi-step reasoning on a query with a selected depth level.
|
|
236
148
|
|
|
237
|
-
|
|
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. |
|
|
238
155
|
|
|
239
|
-
|
|
240
|
-
npm install
|
|
241
|
-
```
|
|
156
|
+
Returns a structured result with session metadata, thoughts, and token usage:
|
|
242
157
|
|
|
243
|
-
|
|
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
|
+
```
|
|
244
179
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
|
248
|
-
|
|
|
249
|
-
|
|
|
250
|
-
|
|
|
251
|
-
|
|
|
252
|
-
|
|
|
180
|
+
### Resources
|
|
181
|
+
|
|
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 |
|
|
189
|
+
|
|
190
|
+
### Prompts
|
|
191
|
+
|
|
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. |
|
|
200
|
+
|
|
201
|
+
### Tasks
|
|
202
|
+
|
|
203
|
+
Task-augmented tool calls are supported for `reasoning.think` with `taskSupport: optional`.
|
|
204
|
+
|
|
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`.
|
|
208
|
+
|
|
209
|
+
## Configuration
|
|
210
|
+
|
|
211
|
+
### Runtime Modes
|
|
212
|
+
|
|
213
|
+
| Mode | Description |
|
|
214
|
+
| ----- | ----------------------------- |
|
|
215
|
+
| stdio | The only supported transport. |
|
|
216
|
+
|
|
217
|
+
### Environment Variables
|
|
218
|
+
|
|
219
|
+
> [!NOTE]
|
|
220
|
+
> Missing info: no environment variables are documented in this repo.
|
|
221
|
+
|
|
222
|
+
## Development
|
|
223
|
+
|
|
224
|
+
Install dependencies:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
npm install
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Scripts:
|
|
231
|
+
|
|
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. |
|
|
243
|
+
|
|
244
|
+
Debug with MCP Inspector:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
npx @modelcontextprotocol/inspector node dist/index.js
|
|
248
|
+
```
|
|
253
249
|
|
|
254
250
|
## Build and Release
|
|
255
251
|
|
|
256
|
-
The
|
|
252
|
+
The GitHub Actions workflow in `.github/workflows/release.yml` automates version bumps, testing, publishing to npm, MCP Registry, and Docker image publishing.
|
|
257
253
|
|
|
258
|
-
|
|
259
|
-
- **Publish**: `npm run prepublishOnly` ensures linting, type-checking, and building before publish.
|
|
254
|
+
Docker support is included via the multi-stage `Dockerfile` and `docker-compose.yml`.
|
|
260
255
|
|
|
261
256
|
## Troubleshooting
|
|
262
257
|
|
|
263
|
-
-
|
|
264
|
-
-
|
|
265
|
-
-
|
|
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.
|
|
266
261
|
|
|
267
262
|
## License
|
|
268
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"}
|