@maximalabs/dev-mcp-suite 0.0.0-stage → 3.6.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/.env.example +69 -0
- package/CHANGELOG.md +281 -0
- package/CODEX_DEV_MCP_GUIDE.md +297 -0
- package/LICENSE +21 -0
- package/README.md +193 -2
- package/armada/package.json +14 -0
- package/armada/server.js +329 -0
- package/backfill-sessions-v2.mjs +288 -0
- package/bin/_meta.mjs +73 -0
- package/bin/armada-mcp.mjs +12 -0
- package/bin/checkpoint.mjs +9 -0
- package/bin/context-pack.mjs +9 -0
- package/bin/devjournal.mjs +9 -0
- package/bin/init.mjs +25 -0
- package/bin/project-memory.mjs +10 -0
- package/bin/provider-smoke.mjs +278 -0
- package/bin/prune.mjs +158 -0
- package/bin/stats.mjs +101 -0
- package/bin/ui.mjs +5 -0
- package/checkpoint/package.json +14 -0
- package/checkpoint/server.js +318 -0
- package/context-pack/package.json +14 -0
- package/context-pack/server.js +747 -0
- package/devjournal/compress.js +75 -0
- package/devjournal/env.js +3 -0
- package/devjournal/package.json +14 -0
- package/devjournal/provider-chain.js +109 -0
- package/devjournal/rerank.js +120 -0
- package/devjournal/server.js +415 -0
- package/docs/ROADMAP.md +77 -0
- package/docs/clients/antigravity.md +52 -0
- package/docs/clients/claude-code.md +46 -0
- package/docs/clients/codex.md +39 -0
- package/docs/clients/generic-mcp.md +45 -0
- package/docs/clients/hermes.md +48 -0
- package/docs/configuration.md +123 -0
- package/docs/privacy.md +39 -0
- package/docs/providers.md +13 -0
- package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md +60 -0
- package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md +65 -0
- package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md +41 -0
- package/docs/superpowers/plans/2026-06-15-trust-release-implementation.md +62 -0
- package/docs/superpowers/plans/2026-06-18-v1-5-0-knowledge-graph.md +792 -0
- package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md +89 -0
- package/docs/superpowers/specs/2026-06-15-trust-release-design.md +164 -0
- package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md +386 -0
- package/docs/superpowers/specs/2026-07-22-v2-0-0-peak-intelligence.md +50 -0
- package/docs/superpowers/specs/2026-07-22-v3-0-0-god-tier.md +32 -0
- package/lib/init-wizard.js +120 -0
- package/lib/provider-smoke.js +234 -0
- package/lib/prune.js +114 -0
- package/lib/stats.js +269 -0
- package/lib/ui-server.js +151 -0
- package/lib/update-check.js +125 -0
- package/package.json +71 -4
- package/project-memory/auto-indexer.js +152 -0
- package/project-memory/dedup.js +49 -0
- package/project-memory/embedding.js +174 -0
- package/project-memory/env.js +3 -0
- package/project-memory/global-index.js +46 -0
- package/project-memory/graph.js +93 -0
- package/project-memory/local-embed.js +92 -0
- package/project-memory/package.json +14 -0
- package/project-memory/provider-chain.js +109 -0
- package/project-memory/rerank.js +120 -0
- package/project-memory/server.js +931 -0
- package/project-memory/swarm.js +56 -0
- package/run-tests.mjs +54 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Hermes Agent Setup
|
|
2
|
+
|
|
3
|
+
`@maximalabs/dev-mcp-suite` is fully compatible with **Hermes Agent** via the standard Model Context Protocol (MCP) stdio interface.
|
|
4
|
+
|
|
5
|
+
## Quick Installation
|
|
6
|
+
|
|
7
|
+
Ensure the package is installed globally or accessible via `npx`:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g @maximalabs/dev-mcp-suite
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Hermes Configuration (`~/.hermes/config.yaml`)
|
|
14
|
+
|
|
15
|
+
Add the suite servers to your Hermes `mcp_servers` configuration block in `~/.hermes/config.yaml`:
|
|
16
|
+
|
|
17
|
+
```yaml
|
|
18
|
+
mcp_servers:
|
|
19
|
+
project-memory:
|
|
20
|
+
command: project-memory-mcp
|
|
21
|
+
args: []
|
|
22
|
+
env:
|
|
23
|
+
MEMORY_VAULT_DIR: "~/.local/share/dev-mcp-suite/memories/vault"
|
|
24
|
+
MCP_LOCAL_EMBED: "true" # Enables zero-dependency local offline vector search
|
|
25
|
+
|
|
26
|
+
devjournal:
|
|
27
|
+
command: devjournal-mcp
|
|
28
|
+
args: []
|
|
29
|
+
env:
|
|
30
|
+
JOURNAL_DIR: "~/.local/share/dev-mcp-suite/memories/journal"
|
|
31
|
+
|
|
32
|
+
checkpoint:
|
|
33
|
+
command: checkpoint-mcp
|
|
34
|
+
args: []
|
|
35
|
+
env:
|
|
36
|
+
CHECKPOINT_DIR: "~/.local/share/dev-mcp-suite/memories/checkpoints"
|
|
37
|
+
|
|
38
|
+
context-pack:
|
|
39
|
+
command: context-pack-mcp
|
|
40
|
+
args: []
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Features Available to Hermes
|
|
44
|
+
|
|
45
|
+
- **`memory_save` / `memory_recall`**: Persistent cross-session memory with optional local offline 384-d term-frequency hashing vector search (`MCP_LOCAL_EMBED=true`).
|
|
46
|
+
- **`journal_log` / `journal_resume` / `journal_handoff`**: Session log & handoff recovery.
|
|
47
|
+
- **`checkpoint_create` / `checkpoint_diff`**: File checkpoints independent of git.
|
|
48
|
+
- **`pack_overview` / `pack_tree` / `pack_audit`**: Codebase orientation & security risk auditing.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
Dev MCP Suite is MCP-client agnostic. The servers run locally over stdio and work in any client that can launch MCP servers: Codex CLI, Claude Code, Cursor, Cline, Gemini-compatible launchers, Hermes, and generic MCP hosts.
|
|
4
|
+
|
|
5
|
+
## Storage
|
|
6
|
+
|
|
7
|
+
All storage is local and file-based.
|
|
8
|
+
|
|
9
|
+
| Env var | Used by | Default |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `MEMORY_VAULT_DIR` | `project-memory` | `~/.codex/memories/vault` |
|
|
12
|
+
| `JOURNAL_DIR` | `devjournal` | `~/.codex/memories/journal` |
|
|
13
|
+
| `CHECKPOINT_DIR` | `checkpoint` | `~/.codex/memories/checkpoints` |
|
|
14
|
+
|
|
15
|
+
Use a different base path if your MCP client is not Codex, for example `~/.local/share/dev-mcp-suite/...`.
|
|
16
|
+
|
|
17
|
+
## Optional model features
|
|
18
|
+
|
|
19
|
+
`context-pack` and `checkpoint` never need a model. `project-memory` and `devjournal` work offline by keyword search and can optionally use an OpenAI-compatible API for better recall.
|
|
20
|
+
|
|
21
|
+
No remote calls are made unless you configure a model endpoint. For strict local-only behavior even when model env vars are present, set `MCP_DETERMINISTIC_FALLBACK=true`.
|
|
22
|
+
|
|
23
|
+
| Env var | Purpose |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `MCP_LLM_BASE_URL` | Base URL for an OpenAI-compatible API, e.g. `http://localhost:11434/v1` or `http://localhost:20128` |
|
|
26
|
+
| `MCP_LLM_API_KEY` | API key for that endpoint; leave blank for local servers that do not require auth |
|
|
27
|
+
| `MCP_RERANK_MODEL` | Chat model for LLM reranking, e.g. `llama3.1:8b`, `kr/claude-haiku-4.5`, `gpt-4o-mini` |
|
|
28
|
+
| `MCP_RERANK_BASE_URL` | Optional rerank-specific base URL; falls back to `MCP_LLM_BASE_URL` |
|
|
29
|
+
| `MCP_RERANK_API_KEY` | Optional rerank-specific API key; falls back to `MCP_LLM_API_KEY` |
|
|
30
|
+
| `RERANK_ENABLED` | Set `0` to disable reranking |
|
|
31
|
+
| `RERANK_TIMEOUT_MS` | Rerank request timeout; default `30000` |
|
|
32
|
+
| `MCP_EMBED_MODEL` | Embedding model for semantic recall, e.g. `nomic-embed-text`, `text-embedding-3-small`, `bm/baai/bge-m3` |
|
|
33
|
+
| `MCP_EMBED_BASE_URL` | Optional embedding-specific base URL; falls back to `MCP_LLM_BASE_URL` |
|
|
34
|
+
| `MCP_EMBED_API_KEY` | Optional embedding-specific API key; falls back to `MCP_LLM_API_KEY` |
|
|
35
|
+
| `EMBED_TIMEOUT_MS` | Embedding request timeout; default `15000` |
|
|
36
|
+
| `MCP_DETERMINISTIC_FALLBACK` | Hard no-network fallback when true; accepts `true`, `1`, `yes`, `on` |
|
|
37
|
+
|
|
38
|
+
Recall mode order:
|
|
39
|
+
|
|
40
|
+
1. `deterministic` if `MCP_DETERMINISTIC_FALLBACK=true`.
|
|
41
|
+
2. `semantic` if embeddings are configured and available.
|
|
42
|
+
3. `rerank` if a chat model is configured and enabled.
|
|
43
|
+
4. `keyword` offline fallback, always available.
|
|
44
|
+
|
|
45
|
+
Failures degrade gracefully. If your embedding endpoint returns `503`, recall falls back to rerank/keyword instead of failing the tool call.
|
|
46
|
+
|
|
47
|
+
## Provider strategy
|
|
48
|
+
|
|
49
|
+
The suite is provider-neutral. A practical remote setup is:
|
|
50
|
+
|
|
51
|
+
1. **Groq** for fast rerank/chat when model quality is sufficient.
|
|
52
|
+
2. **Cerebras** as a second fast provider for outages or model fit.
|
|
53
|
+
3. **OpenRouter** as broad fallback for many OpenAI-compatible models.
|
|
54
|
+
|
|
55
|
+
In `v1.1`, chat/rerank can use built-in numbered fallback slots. Configure only primary if you want one provider, or add more numbered chain entries.
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
MCP_PROVIDER_PRIMARY=groq
|
|
59
|
+
MCP_PROVIDER_PRIMARY_BASE_URL=https://api.groq.com/openai/v1
|
|
60
|
+
MCP_PROVIDER_PRIMARY_API_KEY=<groq-key>
|
|
61
|
+
MCP_PROVIDER_PRIMARY_MODEL=llama-3.3-70b-versatile
|
|
62
|
+
|
|
63
|
+
MCP_PROVIDER_CHAIN2=cerebras
|
|
64
|
+
MCP_PROVIDER_CHAIN2_BASE_URL=https://api.cerebras.ai/v1
|
|
65
|
+
MCP_PROVIDER_CHAIN2_API_KEY=<cerebras-key>
|
|
66
|
+
MCP_PROVIDER_CHAIN2_MODEL=llama-3.3-70b
|
|
67
|
+
|
|
68
|
+
MCP_PROVIDER_CHAIN3=openrouter
|
|
69
|
+
MCP_PROVIDER_CHAIN3_BASE_URL=https://openrouter.ai/api/v1
|
|
70
|
+
MCP_PROVIDER_CHAIN3_API_KEY=<openrouter-key>
|
|
71
|
+
MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
You can add `MCP_PROVIDER_CHAIN4_*`, `MCP_PROVIDER_CHAIN5_*`, and so on. The provider name is only a label; any OpenAI-compatible endpoint works when `BASE_URL`, `API_KEY`, and `MODEL` are set.
|
|
75
|
+
|
|
76
|
+
On a `429`, `5xx`, timeout, or network error, a provider is put on a short cooldown and the next slot is tried. Tune the window with `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
|
|
77
|
+
|
|
78
|
+
## Diagnostics
|
|
79
|
+
|
|
80
|
+
Each server bin supports inspection flags that never start the server:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
project-memory-mcp --version
|
|
84
|
+
project-memory-mcp --doctor # storage + model/provider config, API keys redacted
|
|
85
|
+
project-memory-mcp --help
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`--doctor` reports configured providers and storage paths and shows API keys only as `set (<n> chars)` or `not set`, never the raw value.
|
|
89
|
+
|
|
90
|
+
Example OpenRouter-style config:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
MCP_LLM_BASE_URL=https://openrouter.ai/api/v1
|
|
94
|
+
MCP_LLM_API_KEY=<your-key>
|
|
95
|
+
MCP_RERANK_MODEL=openai/gpt-4o-mini
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Example local-only deterministic config:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
MCP_DETERMINISTIC_FALLBACK=true
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
See [privacy and data flow](privacy.md) before using remote providers with sensitive projects.
|
|
105
|
+
|
|
106
|
+
## Legacy aliases
|
|
107
|
+
|
|
108
|
+
These older names still work for backward compatibility:
|
|
109
|
+
|
|
110
|
+
| Legacy | Preferred |
|
|
111
|
+
|---|---|
|
|
112
|
+
| `LLM_BASE_URL` | `MCP_LLM_BASE_URL` |
|
|
113
|
+
| `LLM_API_KEY` | `MCP_LLM_API_KEY` |
|
|
114
|
+
| `NINEROUTER_URL` | `MCP_LLM_BASE_URL` |
|
|
115
|
+
| `NINEROUTER_KEY` | `MCP_LLM_API_KEY` |
|
|
116
|
+
| `EMBED_MODEL` | `MCP_EMBED_MODEL` |
|
|
117
|
+
| `RERANK_MODEL` | `MCP_RERANK_MODEL` |
|
|
118
|
+
| `EMBED_URL` | `MCP_EMBED_BASE_URL` |
|
|
119
|
+
| `EMBED_KEY` | `MCP_EMBED_API_KEY` |
|
|
120
|
+
| `RERANK_URL` | `MCP_RERANK_BASE_URL` |
|
|
121
|
+
| `RERANK_KEY` | `MCP_RERANK_API_KEY` |
|
|
122
|
+
|
|
123
|
+
Prefer the `MCP_*` names for new installs.
|
package/docs/privacy.md
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Privacy and Data Flow
|
|
2
|
+
|
|
3
|
+
Dev MCP Suite is local-first. It has no hosted backend, no built-in telemetry, and no account system owned by this project.
|
|
4
|
+
|
|
5
|
+
## What is stored locally
|
|
6
|
+
|
|
7
|
+
| Server | Local data |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `project-memory` | Markdown notes, keyword index, optional embedding vectors if you run `memory_reindex` with embeddings configured |
|
|
10
|
+
| `devjournal` | Session logs, handoff files, timeline entries |
|
|
11
|
+
| `checkpoint` | Text-file snapshots for rollback |
|
|
12
|
+
| `context-pack` | No persistent project data by default |
|
|
13
|
+
|
|
14
|
+
Default storage paths are under `~/.codex/memories/...`; you can override them with `MEMORY_VAULT_DIR`, `JOURNAL_DIR`, and `CHECKPOINT_DIR`.
|
|
15
|
+
|
|
16
|
+
## What can leave your machine
|
|
17
|
+
|
|
18
|
+
Nothing leaves your machine by default. `project-memory` and `devjournal` use offline keyword scoring unless you configure an external OpenAI-compatible model endpoint.
|
|
19
|
+
|
|
20
|
+
If you set model environment variables such as `MCP_LLM_BASE_URL`, `MCP_EMBED_BASE_URL`, `MCP_RERANK_BASE_URL`, or numbered provider slots like `MCP_PROVIDER_PRIMARY_BASE_URL`, the related query text and candidate snippets may be sent to that endpoint for embeddings or reranking. The endpoint can be local (Ollama, LM Studio, vLLM, LiteLLM) or remote (Groq, Cerebras, OpenRouter, 9Router, OpenAI-compatible gateways).
|
|
21
|
+
|
|
22
|
+
## Hard no-network mode
|
|
23
|
+
|
|
24
|
+
Set this when you want deterministic local-only recall even if model keys are present:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
MCP_DETERMINISTIC_FALLBACK=true
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Accepted true values: `true`, `1`, `yes`, `on` (case-insensitive). In this mode:
|
|
31
|
+
|
|
32
|
+
- Embeddings are disabled.
|
|
33
|
+
- LLM reranking is disabled.
|
|
34
|
+
- `memory_reindex` skips embedding generation.
|
|
35
|
+
- Results are labeled `[deterministic]`.
|
|
36
|
+
|
|
37
|
+
## Recommended provider posture
|
|
38
|
+
|
|
39
|
+
For remote providers, use least-privilege API keys and configure them per MCP client environment. Do not commit API keys to this repository or project repos. Prefer local models for sensitive work; use remote providers only for projects where sending snippets to that provider is acceptable.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Provider smoke matrix
|
|
2
|
+
|
|
3
|
+
_Generated 2026-06-17T01:58:41.412Z_
|
|
4
|
+
|
|
5
|
+
| Provider | Kind | Status | Latency | HTTP | Sample / dim | Error |
|
|
6
|
+
|---|---|---|---|---|---|---|
|
|
7
|
+
| groq | chat | ✓ | 430ms | 200 | `OK` | |
|
|
8
|
+
| cerebras | chat | ✓ | 554ms | 200 | — | |
|
|
9
|
+
| openai | chat | ✗ | 158ms | 401 | — | {"error":{"message":"unauthorized client detected, contact support for assistance at https://discord.com/invite/V6kaP6Rg44"},"message":"UNAUTHENTICATED","success":false,"type":"unauthorized_client_err |
|
|
10
|
+
| openai | embed | ✗ | 147ms | 401 | — | {"error":{"message":"unauthorized client detected, contact support for assistance at https://discord.com/invite/V6kaP6Rg44"},"message":"UNAUTHENTICATED","success":false,"type":"unauthorized_client_err |
|
|
11
|
+
| anthropic | chat | ✓ | 5.83s | 200 | — | |
|
|
12
|
+
| cloudflare | chat | ✗ | 907ms | 400 | — | {"errors":[{"message":"AiError: Bad input: Error: oneOf at '/' not met, 0 matches: required properties at '/' are 'text', required properties at '/' are 'requests' (f3f58c5f-7207-461a-96e1-d809e15ede3 |
|
|
13
|
+
| cloudflare | embed | ✓ | 194ms | 200 | dim=768 | |
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Hardening v1.2 Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** Add CLI UX (help/version/doctor), secret redaction, provider validation, per-provider timeout + 429/5xx cooldown, and a packaged-tarball CI smoke test, without breaking existing behavior.
|
|
6
|
+
|
|
7
|
+
**Architecture:** Add a shared bin meta-handler that intercepts `--help/--version/--doctor` before starting the stdio server. Add redaction + provider diagnostics + cooldown helpers in the provider layer. Wire rerank chat calls through cooldown-aware provider iteration. Extend CI with a tarball install smoke job.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Node.js ESM, existing MCP SDK servers, built-in `http`/`https`, offline test harness, GitHub Actions.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
### Task 1: Bin CLI Meta (help/version/doctor)
|
|
14
|
+
|
|
15
|
+
**Files:**
|
|
16
|
+
- Create: `bin/_meta.mjs`
|
|
17
|
+
- Modify: `bin/project-memory.mjs`, `bin/devjournal.mjs`, `bin/checkpoint.mjs`, `bin/context-pack.mjs`
|
|
18
|
+
|
|
19
|
+
- [ ] Add `handleCliMeta({ bin, title, serverDir })` that handles `-h/--help`, `-v/--version`, `--doctor` then exits; returns false otherwise.
|
|
20
|
+
- [ ] Read version from root `package.json`.
|
|
21
|
+
- [ ] `--doctor` prints storage + model/provider config with API keys redacted (never raw values).
|
|
22
|
+
- [ ] Each bin calls meta first, then imports its server only when not handled.
|
|
23
|
+
|
|
24
|
+
### Task 2: Redaction + Provider Diagnostics + Cooldown
|
|
25
|
+
|
|
26
|
+
**Files:**
|
|
27
|
+
- Modify: `project-memory/provider-chain.js`, `devjournal/provider-chain.js`
|
|
28
|
+
|
|
29
|
+
- [ ] Add `redactKey(value)` returning `set (<n> chars)` / `not set`, never the value.
|
|
30
|
+
- [ ] Add `providerChainDiagnostics()` listing active providers (redacted) and incomplete-slot issues.
|
|
31
|
+
- [ ] Add pure cooldown helpers `recordOutcome(key, ok, now)` and `isCoolingDown(key, now)` using `MCP_PROVIDER_COOLDOWN_MS` (default 60000).
|
|
32
|
+
|
|
33
|
+
### Task 3: Cooldown-Aware Rerank
|
|
34
|
+
|
|
35
|
+
**Files:**
|
|
36
|
+
- Modify: `project-memory/rerank.js`, `devjournal/rerank.js`
|
|
37
|
+
|
|
38
|
+
- [ ] Make provider chat return status so 429/5xx/network failures are retryable.
|
|
39
|
+
- [ ] Skip providers currently cooling down; record outcomes.
|
|
40
|
+
- [ ] Stop after first success; fall back to keyword if all fail. Never log keys/bodies.
|
|
41
|
+
|
|
42
|
+
### Task 4: Tests
|
|
43
|
+
|
|
44
|
+
**Files:**
|
|
45
|
+
- Modify: `project-memory/test.mjs`, `devjournal/test.mjs`
|
|
46
|
+
|
|
47
|
+
- [ ] Test `providerChainDiagnostics()` flags an incomplete slot and redacts keys.
|
|
48
|
+
- [ ] Test cooldown helpers: failure starts cooldown, expiry clears it, success clears it.
|
|
49
|
+
- [ ] Test bin `--version` prints package version and `--doctor` output excludes raw key value.
|
|
50
|
+
|
|
51
|
+
### Task 5: CI Tarball Smoke + Verify
|
|
52
|
+
|
|
53
|
+
**Files:**
|
|
54
|
+
- Modify: `.github/workflows/ci.yml`
|
|
55
|
+
- Modify: `CHANGELOG.md`, `package.json`, `docs/configuration.md`, `.env.example`
|
|
56
|
+
|
|
57
|
+
- [ ] Add CI job: `npm pack`, install tarball in temp dir, run each bin `--version`.
|
|
58
|
+
- [ ] Document `--doctor` and `MCP_PROVIDER_COOLDOWN_MS`.
|
|
59
|
+
- [ ] Bump version to 1.2.0 and add changelog entry.
|
|
60
|
+
- [ ] Run `npm test` and `npm pack --dry-run`; expect all pass.
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Provider Chain v1.1 Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** Add optional numbered OpenAI-compatible provider fallback for rerank/chat calls while preserving deterministic no-network mode and legacy env compatibility.
|
|
6
|
+
|
|
7
|
+
**Architecture:** Add focused provider-chain helpers to `project-memory` and `devjournal`, then route existing rerank chat calls through those helpers. Provider slots are built from `MCP_PROVIDER_PRIMARY_*`, `MCP_PROVIDER_CHAIN2_*`, `MCP_PROVIDER_CHAIN3_*`, etc.; if absent, existing `MCP_RERANK_*`/`MCP_LLM_*`/legacy config is used.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Node.js ESM, existing MCP SDK servers, built-in `http`/`https`, existing offline test harness.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
### Task 1: Provider Chain Helpers
|
|
14
|
+
|
|
15
|
+
**Files:**
|
|
16
|
+
- Create: `project-memory/provider-chain.js`
|
|
17
|
+
- Create: `devjournal/provider-chain.js`
|
|
18
|
+
- Test: `project-memory/test.mjs`
|
|
19
|
+
- Test: `devjournal/test.mjs`
|
|
20
|
+
|
|
21
|
+
- [ ] Create a `providerEnv(slotPrefix)` helper that reads `NAME`, `BASE_URL`, `API_KEY`, and `MODEL` from a prefix such as `MCP_PROVIDER_PRIMARY`.
|
|
22
|
+
- [ ] Create `providerChainConfig()` returning `{ providers, enabled, deterministic }`.
|
|
23
|
+
- [ ] Include `MCP_PROVIDER_PRIMARY` first when complete.
|
|
24
|
+
- [ ] Include every complete numbered slot matching `MCP_PROVIDER_CHAIN<N>` in numeric order for `N >= 2`.
|
|
25
|
+
- [ ] Fall back to one legacy provider from existing rerank/LLM envs when no numbered slots exist.
|
|
26
|
+
- [ ] Return disabled config if deterministic mode is on.
|
|
27
|
+
- [ ] Add tests for primary-only, primary+chain2+chain3 ordering, arbitrary chain4, incomplete slot skip, deterministic disable, and legacy fallback.
|
|
28
|
+
|
|
29
|
+
### Task 2: Rerank Uses Provider Chain
|
|
30
|
+
|
|
31
|
+
**Files:**
|
|
32
|
+
- Modify: `project-memory/rerank.js`
|
|
33
|
+
- Modify: `devjournal/rerank.js`
|
|
34
|
+
- Test: existing `npm test`
|
|
35
|
+
|
|
36
|
+
- [ ] Replace single `BASE`/`KEY`/`MODEL` request selection with `providerChainConfig()`.
|
|
37
|
+
- [ ] Try providers in order for each chat request.
|
|
38
|
+
- [ ] Return first valid OpenAI-compatible response.
|
|
39
|
+
- [ ] On non-200, timeout, network error, invalid JSON, or SSE parse failure, try the next provider.
|
|
40
|
+
- [ ] Keep returning `null` if every provider fails so keyword fallback still works.
|
|
41
|
+
- [ ] Never log API keys or response bodies.
|
|
42
|
+
|
|
43
|
+
### Task 3: Docs and Examples
|
|
44
|
+
|
|
45
|
+
**Files:**
|
|
46
|
+
- Modify: `docs/configuration.md`
|
|
47
|
+
- Modify: `docs/privacy.md`
|
|
48
|
+
- Modify: `.env.example`
|
|
49
|
+
- Modify: `CHANGELOG.md`
|
|
50
|
+
- Modify: `README.md` if needed
|
|
51
|
+
|
|
52
|
+
- [ ] Document numbered provider slots.
|
|
53
|
+
- [ ] Document Groq/Cerebras/OpenRouter as recommended examples, not required providers.
|
|
54
|
+
- [ ] Clarify users can use any OpenAI-compatible base URL, token, and model ID.
|
|
55
|
+
- [ ] Clarify deterministic mode overrides provider chain.
|
|
56
|
+
- [ ] Add changelog entry for v1.1 unreleased.
|
|
57
|
+
|
|
58
|
+
### Task 4: Verification
|
|
59
|
+
|
|
60
|
+
**Files:**
|
|
61
|
+
- No source changes.
|
|
62
|
+
|
|
63
|
+
- [ ] Run `npm test` and expect 33+ tests all pass.
|
|
64
|
+
- [ ] Run `npm pack --dry-run` and confirm runtime provider-chain helpers are included.
|
|
65
|
+
- [ ] Run secret scan on changed/staged files and confirm no real secrets.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Provider- and Client-Agnostic Config Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** Make the MCP suite configurable for any OpenAI-compatible gateway and document usage beyond Codex.
|
|
6
|
+
|
|
7
|
+
**Architecture:** Keep backward compatibility with existing `NINEROUTER_*` env vars while introducing neutral `MCP_*` env names. Documentation separates generic install, provider config, and client-specific config examples.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Node.js MCP servers, OpenAI-compatible HTTP APIs for embeddings/rerank, Markdown docs.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
### Task 1: Neutral Provider Env Aliases
|
|
14
|
+
|
|
15
|
+
**Files:**
|
|
16
|
+
- Modify: `project-memory/embedding.js`
|
|
17
|
+
- Modify: `project-memory/rerank.js`
|
|
18
|
+
- Modify: `devjournal/rerank.js`
|
|
19
|
+
- Test: existing `npm test`
|
|
20
|
+
|
|
21
|
+
- [ ] Add `MCP_EMBED_BASE_URL`, `MCP_EMBED_API_KEY`, `MCP_EMBED_MODEL` with fallback to existing `NINEROUTER_URL`, `NINEROUTER_KEY`, `EMBED_MODEL`.
|
|
22
|
+
- [ ] Add `MCP_LLM_BASE_URL`, `MCP_LLM_API_KEY`, `MCP_RERANK_MODEL` with fallback to existing `NINEROUTER_URL`, `NINEROUTER_KEY`, `RERANK_MODEL`.
|
|
23
|
+
- [ ] Keep default disabled behavior when no key/url/model is configured.
|
|
24
|
+
- [ ] Run `npm test` and expect all tests pass.
|
|
25
|
+
|
|
26
|
+
### Task 2: Client-Agnostic Docs
|
|
27
|
+
|
|
28
|
+
**Files:**
|
|
29
|
+
- Create: `docs/configuration.md`
|
|
30
|
+
- Create: `docs/clients/codex.md`
|
|
31
|
+
- Create: `docs/clients/claude-code.md`
|
|
32
|
+
- Create: `docs/clients/generic-mcp.md`
|
|
33
|
+
- Modify: `.env.example`
|
|
34
|
+
- Modify: `README.md`
|
|
35
|
+
|
|
36
|
+
- [ ] Document neutral env names and legacy aliases.
|
|
37
|
+
- [ ] Provide Codex TOML config using npm bin commands.
|
|
38
|
+
- [ ] Provide Claude Code MCP JSON config using npm bin commands.
|
|
39
|
+
- [ ] Provide generic MCP JSON config.
|
|
40
|
+
- [ ] Update README to call the suite “Dev MCP Suite” while preserving package name.
|
|
41
|
+
- [ ] Run tests again after docs changes.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Trust Release Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** Implement the approved v1.0.1 trust release: privacy docs, deterministic no-network mode, provider recommendation docs, tests, and publish readiness checks.
|
|
6
|
+
|
|
7
|
+
**Architecture:** Add a tiny shared environment parser for deterministic mode in each server area that needs it, then gate embedding/rerank call paths before any network request is attempted. Documentation explains data flow and optional provider setup without enabling remote calls by default.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Node.js MCP servers, Markdown docs, existing offline MCP test harness.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
### Task 1: Deterministic Mode Code
|
|
14
|
+
|
|
15
|
+
**Files:**
|
|
16
|
+
- Modify: `project-memory/server.js`
|
|
17
|
+
- Modify: `project-memory/embedding.js`
|
|
18
|
+
- Modify: `project-memory/rerank.js`
|
|
19
|
+
- Modify: `devjournal/server.js`
|
|
20
|
+
- Modify: `devjournal/rerank.js`
|
|
21
|
+
|
|
22
|
+
- [ ] Add `deterministicEnabled()` helper that accepts `true`, `1`, `yes`, `on` case-insensitive.
|
|
23
|
+
- [ ] In project-memory, skip embedding and rerank when deterministic is enabled.
|
|
24
|
+
- [ ] In project-memory, label recall results `[deterministic]` when deterministic is enabled.
|
|
25
|
+
- [ ] In project-memory, make reindex report deterministic/no-network instead of attempting embeddings.
|
|
26
|
+
- [ ] In devjournal, skip rerank and label search `[deterministic]` when deterministic is enabled.
|
|
27
|
+
|
|
28
|
+
### Task 2: Deterministic Tests
|
|
29
|
+
|
|
30
|
+
**Files:**
|
|
31
|
+
- Modify: `project-memory/test.mjs`
|
|
32
|
+
- Modify: `devjournal/test.mjs`
|
|
33
|
+
|
|
34
|
+
- [ ] Add project-memory test proving deterministic mode labels recall `[deterministic]`.
|
|
35
|
+
- [ ] Add project-memory test proving reindex reports deterministic/no-network.
|
|
36
|
+
- [ ] Add devjournal test proving deterministic mode labels search `[deterministic]`.
|
|
37
|
+
- [ ] Add env parsing test for `true`, `1`, `yes`, `on`.
|
|
38
|
+
|
|
39
|
+
### Task 3: Trust Docs
|
|
40
|
+
|
|
41
|
+
**Files:**
|
|
42
|
+
- Create: `docs/privacy.md`
|
|
43
|
+
- Modify: `docs/configuration.md`
|
|
44
|
+
- Modify: `README.md`
|
|
45
|
+
- Modify: `.env.example`
|
|
46
|
+
- Modify: `CHANGELOG.md`
|
|
47
|
+
- Modify: `package.json`
|
|
48
|
+
|
|
49
|
+
- [ ] Add privacy/data-flow doc.
|
|
50
|
+
- [ ] Add deterministic env docs.
|
|
51
|
+
- [ ] Add Groq/Cerebras/OpenRouter docs-only provider strategy.
|
|
52
|
+
- [ ] Include `docs/privacy.md` in npm package files.
|
|
53
|
+
- [ ] Update changelog with trust-release items.
|
|
54
|
+
|
|
55
|
+
### Task 4: Verification
|
|
56
|
+
|
|
57
|
+
**Files:**
|
|
58
|
+
- No code files.
|
|
59
|
+
|
|
60
|
+
- [ ] Run `npm test` and expect all tests pass.
|
|
61
|
+
- [ ] Run `npm pack --dry-run` and confirm public docs included, internal plans/specs excluded.
|
|
62
|
+
- [ ] Run secret scan and confirm no real secrets.
|