@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,109 @@
|
|
|
1
|
+
import { deterministicEnabled } from "./env.js";
|
|
2
|
+
|
|
3
|
+
const DEFAULT_BASE = "http://localhost:20128";
|
|
4
|
+
const DEFAULT_MODEL = "kr/claude-haiku-4.5";
|
|
5
|
+
|
|
6
|
+
function value(name) {
|
|
7
|
+
return String(process.env[name] || "").trim();
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
export function redactKey(key) {
|
|
11
|
+
const k = String(key || "");
|
|
12
|
+
return k ? `set (${k.length} chars)` : "not set";
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function providerEnv(prefix) {
|
|
16
|
+
const label = value(prefix);
|
|
17
|
+
const base = value(`${prefix}_BASE_URL`);
|
|
18
|
+
const key = value(`${prefix}_API_KEY`);
|
|
19
|
+
const model = value(`${prefix}_MODEL`);
|
|
20
|
+
if (!label || !base || !key || !model) return null;
|
|
21
|
+
return { label, base, key, model };
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
function slotIssues(prefix) {
|
|
25
|
+
const present = ["", "_BASE_URL", "_API_KEY", "_MODEL"].some((s) => value(`${prefix}${s}`));
|
|
26
|
+
if (!present) return null;
|
|
27
|
+
const missing = [];
|
|
28
|
+
if (!value(prefix)) missing.push(`${prefix}`);
|
|
29
|
+
if (!value(`${prefix}_BASE_URL`)) missing.push(`${prefix}_BASE_URL`);
|
|
30
|
+
if (!value(`${prefix}_API_KEY`)) missing.push(`${prefix}_API_KEY`);
|
|
31
|
+
if (!value(`${prefix}_MODEL`)) missing.push(`${prefix}_MODEL`);
|
|
32
|
+
return missing.length ? { prefix, missing } : null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function numberedPrefixes() {
|
|
36
|
+
const prefixes = ["MCP_PROVIDER_PRIMARY"];
|
|
37
|
+
const nums = Object.keys(process.env)
|
|
38
|
+
.map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)/)?.[1])
|
|
39
|
+
.filter(Boolean)
|
|
40
|
+
.map(Number)
|
|
41
|
+
.filter((n) => n >= 2);
|
|
42
|
+
for (const n of [...new Set(nums)].sort((a, b) => a - b)) {
|
|
43
|
+
prefixes.push(`MCP_PROVIDER_CHAIN${n}`);
|
|
44
|
+
}
|
|
45
|
+
return prefixes;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function numberedProviders() {
|
|
49
|
+
const providers = [];
|
|
50
|
+
for (const prefix of numberedPrefixes()) {
|
|
51
|
+
const provider = providerEnv(prefix);
|
|
52
|
+
if (provider) providers.push(provider);
|
|
53
|
+
}
|
|
54
|
+
return providers;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function legacyProvider() {
|
|
58
|
+
const base = value("MCP_RERANK_BASE_URL") || value("MCP_LLM_BASE_URL") || value("LLM_BASE_URL") || value("RERANK_URL") || value("NINEROUTER_URL") || DEFAULT_BASE;
|
|
59
|
+
const key = value("MCP_RERANK_API_KEY") || value("MCP_LLM_API_KEY") || value("LLM_API_KEY") || value("RERANK_KEY") || value("NINEROUTER_KEY");
|
|
60
|
+
const model = value("MCP_RERANK_MODEL") || value("RERANK_MODEL") || DEFAULT_MODEL;
|
|
61
|
+
if (!key) return null;
|
|
62
|
+
return { label: "legacy", base, key, model };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export function providerChainConfig() {
|
|
66
|
+
const deterministic = deterministicEnabled();
|
|
67
|
+
const rerankEnabled = process.env.RERANK_ENABLED !== "0";
|
|
68
|
+
if (deterministic || !rerankEnabled) return { providers: [], enabled: false, deterministic };
|
|
69
|
+
const providers = numberedProviders();
|
|
70
|
+
if (providers.length === 0) {
|
|
71
|
+
const legacy = legacyProvider();
|
|
72
|
+
if (legacy) providers.push(legacy);
|
|
73
|
+
}
|
|
74
|
+
return { providers, enabled: providers.length > 0, deterministic };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function providerChainDiagnostics() {
|
|
78
|
+
const cfg = providerChainConfig();
|
|
79
|
+
const issues = [];
|
|
80
|
+
for (const prefix of numberedPrefixes()) {
|
|
81
|
+
const issue = slotIssues(prefix);
|
|
82
|
+
if (issue) issues.push(issue);
|
|
83
|
+
}
|
|
84
|
+
return {
|
|
85
|
+
deterministic: cfg.deterministic,
|
|
86
|
+
enabled: cfg.enabled,
|
|
87
|
+
providers: cfg.providers.map((p) => ({ label: p.label, base: p.base, model: p.model, apiKey: redactKey(p.key) })),
|
|
88
|
+
issues,
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const COOLDOWN_MS = Number(process.env.MCP_PROVIDER_COOLDOWN_MS || 60000);
|
|
93
|
+
const cooldowns = new Map();
|
|
94
|
+
|
|
95
|
+
export function isCoolingDown(key, now = Date.now()) {
|
|
96
|
+
const until = cooldowns.get(key);
|
|
97
|
+
if (!until) return false;
|
|
98
|
+
if (now >= until) { cooldowns.delete(key); return false; }
|
|
99
|
+
return true;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export function recordOutcome(key, ok, now = Date.now()) {
|
|
103
|
+
if (ok) { cooldowns.delete(key); return; }
|
|
104
|
+
cooldowns.set(key, now + COOLDOWN_MS);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export function _resetCooldowns() {
|
|
108
|
+
cooldowns.clear();
|
|
109
|
+
}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* LLM reranker via any OpenAI-compatible /v1/chat/completions model.
|
|
3
|
+
* Tries provider chain slots in order, skipping any currently cooling down
|
|
4
|
+
* after a recent failure. Degrades gracefully: returns null on any failure so
|
|
5
|
+
* callers fall back to keyword ordering. Never throws. Never logs keys/bodies.
|
|
6
|
+
*/
|
|
7
|
+
import http from "http";
|
|
8
|
+
import https from "https";
|
|
9
|
+
import { URL } from "url";
|
|
10
|
+
import { deterministicEnabled } from "./env.js";
|
|
11
|
+
import { providerChainConfig, isCoolingDown, recordOutcome } from "./provider-chain.js";
|
|
12
|
+
|
|
13
|
+
const TIMEOUT_MS = Number(process.env.RERANK_TIMEOUT_MS || 30000);
|
|
14
|
+
const ENABLED = process.env.RERANK_ENABLED !== "0";
|
|
15
|
+
|
|
16
|
+
export function rerankConfig() {
|
|
17
|
+
const cfg = providerChainConfig();
|
|
18
|
+
const first = cfg.providers[0] || {};
|
|
19
|
+
return {
|
|
20
|
+
base: first.base,
|
|
21
|
+
model: first.model,
|
|
22
|
+
providers: cfg.providers.map(({ label, base, model }) => ({ label, base, model })),
|
|
23
|
+
enabled: ENABLED && cfg.enabled && !deterministicEnabled(),
|
|
24
|
+
deterministic: deterministicEnabled(),
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function providerKey(provider) {
|
|
29
|
+
return `${provider.label}|${provider.base}|${provider.model}`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Resolves { content, retryable }. retryable=true means try the next provider
|
|
34
|
+
* (timeout, network error, 429, or 5xx). retryable=false with null content
|
|
35
|
+
* means a definitive non-retryable response (e.g. 4xx auth).
|
|
36
|
+
*/
|
|
37
|
+
function chatWithProvider(provider, messages) {
|
|
38
|
+
return new Promise((resolve) => {
|
|
39
|
+
let u;
|
|
40
|
+
try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve({ content: null, retryable: false }); }
|
|
41
|
+
const payload = Buffer.from(JSON.stringify({ model: provider.model, stream: false, temperature: 0, max_tokens: 200, messages }));
|
|
42
|
+
const lib = u.protocol === "https:" ? https : http;
|
|
43
|
+
const req = lib.request(
|
|
44
|
+
{
|
|
45
|
+
hostname: u.hostname,
|
|
46
|
+
port: u.port || (u.protocol === "https:" ? 443 : 80),
|
|
47
|
+
path: u.pathname,
|
|
48
|
+
method: "POST",
|
|
49
|
+
headers: { "Content-Type": "application/json", "Content-Length": payload.length, Authorization: `Bearer ${provider.key}` },
|
|
50
|
+
timeout: TIMEOUT_MS,
|
|
51
|
+
},
|
|
52
|
+
(res) => {
|
|
53
|
+
let body = "";
|
|
54
|
+
res.on("data", (c) => (body += c));
|
|
55
|
+
res.on("end", () => {
|
|
56
|
+
const status = res.statusCode || 0;
|
|
57
|
+
if (status !== 200) {
|
|
58
|
+
const retryable = status === 429 || status >= 500;
|
|
59
|
+
return resolve({ content: null, retryable });
|
|
60
|
+
}
|
|
61
|
+
try {
|
|
62
|
+
const j = JSON.parse(body);
|
|
63
|
+
return resolve({ content: j?.choices?.[0]?.message?.content ?? null, retryable: false });
|
|
64
|
+
} catch { /* maybe SSE */ }
|
|
65
|
+
try {
|
|
66
|
+
let acc = "";
|
|
67
|
+
for (const line of body.split("\n")) {
|
|
68
|
+
const t = line.trim();
|
|
69
|
+
if (!t.startsWith("data:")) continue;
|
|
70
|
+
const d = t.slice(5).trim();
|
|
71
|
+
if (d === "[DONE]") break;
|
|
72
|
+
const j = JSON.parse(d);
|
|
73
|
+
acc += j?.choices?.[0]?.delta?.content || j?.choices?.[0]?.message?.content || "";
|
|
74
|
+
}
|
|
75
|
+
return resolve({ content: acc || null, retryable: false });
|
|
76
|
+
} catch { return resolve({ content: null, retryable: true }); }
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
);
|
|
80
|
+
req.on("error", () => resolve({ content: null, retryable: true }));
|
|
81
|
+
req.on("timeout", () => { req.destroy(); resolve({ content: null, retryable: true }); });
|
|
82
|
+
req.write(payload);
|
|
83
|
+
req.end();
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
async function chat(messages) {
|
|
88
|
+
if (!ENABLED || deterministicEnabled()) return null;
|
|
89
|
+
const { providers } = providerChainConfig();
|
|
90
|
+
for (const provider of providers) {
|
|
91
|
+
const key = providerKey(provider);
|
|
92
|
+
if (isCoolingDown(key)) continue;
|
|
93
|
+
const { content, retryable } = await chatWithProvider(provider, messages);
|
|
94
|
+
if (content) { recordOutcome(key, true); return content; }
|
|
95
|
+
if (retryable) recordOutcome(key, false);
|
|
96
|
+
}
|
|
97
|
+
return null;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Given a query and candidates [{id, title, snippet}], ask the model to return
|
|
102
|
+
* the ids ordered by relevance. Returns an array of ids, or null on failure.
|
|
103
|
+
*/
|
|
104
|
+
export async function rerank(query, candidates, topK = 5) {
|
|
105
|
+
if (!ENABLED || deterministicEnabled() || !candidates || candidates.length === 0 || !providerChainConfig().enabled) return null;
|
|
106
|
+
const list = candidates.map((c, i) => `[${i + 1}] (id:${c.id}) ${c.title}\n ${String(c.snippet || "").replace(/\s+/g, " ").slice(0, 200)}`).join("\n");
|
|
107
|
+
const sys = "You are a search reranker. Given a user query and a numbered list of notes, return the most relevant notes ordered best-first. Respond with ONLY a comma-separated list of the bracket numbers, e.g. 3,1,5. No prose.";
|
|
108
|
+
const user = `Query: ${query}\n\nNotes:\n${list}\n\nReturn the top ${topK} bracket numbers, best first, comma-separated:`;
|
|
109
|
+
const out = await chat([{ role: "system", content: sys }, { role: "user", content: user }]);
|
|
110
|
+
if (!out) return null;
|
|
111
|
+
const nums = (out.match(/\d+/g) || []).map(Number).filter((n) => n >= 1 && n <= candidates.length);
|
|
112
|
+
if (nums.length === 0) return null;
|
|
113
|
+
const seen = new Set();
|
|
114
|
+
const ordered = [];
|
|
115
|
+
for (const n of nums) {
|
|
116
|
+
const id = candidates[n - 1]?.id;
|
|
117
|
+
if (id && !seen.has(id)) { seen.add(id); ordered.push(id); }
|
|
118
|
+
}
|
|
119
|
+
return ordered.length ? ordered : null;
|
|
120
|
+
}
|