@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,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Context compressor for devjournal.
|
|
3
|
+
* Condenses verbose timeline entries into a ultra-compact (~500 token) snapshot.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import fs from "fs/promises";
|
|
7
|
+
import path from "path";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Compress journal entries for a project into a dense markdown summary block.
|
|
11
|
+
*/
|
|
12
|
+
export async function compressJournalEntries(journalDir, projectSlug, { limit = 50, maxTokens = 500 } = {}) {
|
|
13
|
+
const projectDir = path.join(journalDir, projectSlug);
|
|
14
|
+
const logFile = path.join(projectDir, "log.jsonl");
|
|
15
|
+
|
|
16
|
+
try {
|
|
17
|
+
const raw = await fs.readFile(logFile, "utf8");
|
|
18
|
+
const lines = raw.split("\n").filter((l) => l.trim().length > 0);
|
|
19
|
+
const entries = lines.map((l) => JSON.parse(l));
|
|
20
|
+
|
|
21
|
+
// Sort newest first
|
|
22
|
+
entries.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
|
|
23
|
+
const recent = entries.slice(0, limit);
|
|
24
|
+
|
|
25
|
+
// Aggregate findings, decisions, files, and blockers
|
|
26
|
+
const decisions = [];
|
|
27
|
+
const blockers = [];
|
|
28
|
+
const filesTouched = new Set();
|
|
29
|
+
|
|
30
|
+
for (const e of recent) {
|
|
31
|
+
if (e.entryType === "decision" || e.tags?.includes("decision")) {
|
|
32
|
+
decisions.push(e.text || e.summary);
|
|
33
|
+
} else if (e.entryType === "blocker" || e.tags?.includes("blocker") || e.tags?.includes("error")) {
|
|
34
|
+
blockers.push(e.text || e.summary);
|
|
35
|
+
}
|
|
36
|
+
if (e.file || e.files) {
|
|
37
|
+
const arr = Array.isArray(e.files) ? e.files : [e.file];
|
|
38
|
+
arr.forEach((f) => f && filesTouched.add(f));
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const outputLines = [
|
|
43
|
+
`# Compressed Journal Snapshot: ${projectSlug}`,
|
|
44
|
+
`Generated: ${new Date().toISOString()}`,
|
|
45
|
+
`Entries Processed: ${recent.length}`,
|
|
46
|
+
``,
|
|
47
|
+
`## 💡 Key Decisions (${decisions.length})`,
|
|
48
|
+
...(decisions.length ? decisions.slice(0, 10).map((d) => `- ${d}`) : ["- None recorded"]),
|
|
49
|
+
``,
|
|
50
|
+
`## ⚠️ Resolved/Active Blockers (${blockers.length})`,
|
|
51
|
+
...(blockers.length ? blockers.slice(0, 10).map((b) => `- ${b}`) : ["- None"]),
|
|
52
|
+
``,
|
|
53
|
+
`## 📁 Files Touched (${filesTouched.size})`,
|
|
54
|
+
...(filesTouched.size ? Array.from(filesTouched).slice(0, 15).map((f) => `- \`${f}\``) : ["- None"]),
|
|
55
|
+
``,
|
|
56
|
+
`## 📝 Latest Entry`,
|
|
57
|
+
recent[0] ? `> ${recent[0].text || recent[0].summary} (${recent[0].timestamp})` : "No entries."
|
|
58
|
+
];
|
|
59
|
+
|
|
60
|
+
const resultText = outputLines.join("\n");
|
|
61
|
+
return {
|
|
62
|
+
projectSlug,
|
|
63
|
+
compressedText: resultText,
|
|
64
|
+
entriesCount: recent.length,
|
|
65
|
+
estimatedTokenCount: Math.ceil(resultText.length / 4),
|
|
66
|
+
};
|
|
67
|
+
} catch {
|
|
68
|
+
return {
|
|
69
|
+
projectSlug,
|
|
70
|
+
compressedText: `# Compressed Journal Snapshot: ${projectSlug}\nNo log entries found.`,
|
|
71
|
+
entriesCount: 0,
|
|
72
|
+
estimatedTokenCount: 15,
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "devjournal-mcp",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Per-project dev journal: session logs, decisions, next-steps timeline",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "server.js",
|
|
7
|
+
"scripts": {
|
|
8
|
+
"start": "node server.js",
|
|
9
|
+
"test": "node test.mjs"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@modelcontextprotocol/sdk": "^1.0.0"
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -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
|
+
}
|