Files
DataStack/server/mcp/mcpEngine.js
T

1333 lines
41 KiB
JavaScript
Raw Normal View History

const crypto = require('node:crypto');
const fs = require('node:fs');
const fsp = require('node:fs/promises');
const path = require('node:path');
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
const {
StreamableHTTPServerTransport,
} = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
const { z } = require('zod');
const { scrubSensitiveLogText } = require('../runtimeLogCapture');
const MCP_PERMISSION_KEYS = [
'metrics_health_read',
'runtime_logs_read',
'build_logs_read',
'audit_logs_read',
'ingestion_events_read',
'clients_read',
'clients_create',
'clients_update',
'clients_revoke_delete',
'files_list_read',
'files_download',
'files_upload_create',
'files_edit',
'files_delete',
'settings_read',
'settings_write',
'storage_maintenance',
];
const DEFAULT_MCP_PERMISSIONS = {
metrics_health_read: true,
runtime_logs_read: true,
build_logs_read: true,
audit_logs_read: true,
ingestion_events_read: true,
clients_read: true,
clients_create: false,
clients_update: false,
clients_revoke_delete: false,
files_list_read: true,
files_download: true,
files_upload_create: false,
files_edit: false,
files_delete: false,
settings_read: true,
settings_write: false,
storage_maintenance: false,
};
const MAX_READ_BYTES = 512 * 1024;
const MAX_WRITE_BYTES = 1024 * 1024;
const MAX_IN_MEMORY_AUDIT_LOGS = 1000;
function normalizeMcpPermissions(raw, base = DEFAULT_MCP_PERMISSIONS) {
const out = { ...base };
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
return out;
}
for (const key of MCP_PERMISSION_KEYS) {
if (typeof raw[key] === 'boolean') {
out[key] = raw[key];
}
}
return out;
}
function hashMcpToken(rawToken) {
return crypto
.createHash('sha256')
.update(String(rawToken || ''), 'utf8')
.digest('hex');
}
function verifyMcpBearerTokenHash(presentedToken, expectedHashHex) {
const cleanPresented = String(presentedToken || '').trim();
const cleanExpected = String(expectedHashHex || '')
.trim()
.toLowerCase();
if (!cleanPresented || cleanExpected.length !== 64) {
return false;
}
try {
const presentedBuf = Buffer.from(hashMcpToken(cleanPresented), 'hex');
const expectedBuf = Buffer.from(cleanExpected, 'hex');
if (presentedBuf.length !== expectedBuf.length) {
return false;
}
return crypto.timingSafeEqual(presentedBuf, expectedBuf);
} catch {
return false;
}
}
function extractMcpClientIp(req) {
const headers = (req && req.headers) || {};
const realIp =
typeof headers['x-real-ip'] === 'string' ? headers['x-real-ip'].trim() : '';
if (realIp) {
return realIp.slice(0, 128);
}
const forwardedFor =
typeof headers['x-forwarded-for'] === 'string'
? headers['x-forwarded-for']
: '';
if (forwardedFor) {
const hops = forwardedFor
.split(',')
.map((p) => p.trim())
.filter(Boolean);
const rightmost = hops[hops.length - 1];
if (rightmost) {
return rightmost.slice(0, 128);
}
}
const socketIp =
(req && req.socket && req.socket.remoteAddress) || (req && req.ip) || '';
return String(socketIp).trim() || '127.0.0.1';
}
function sanitizeAuditMeta(meta) {
if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return {};
const REDACTED = new Set([
'token',
'secret',
'password',
'mcpToken',
'mcpBearerToken',
'issuedToken',
'tokenHash',
'tokenEnc',
'coolifyToken',
'coolifyTokenEnc',
'authorization',
]);
const clean = {};
for (const [k, v] of Object.entries(meta)) {
clean[k] = REDACTED.has(k) ? '[REDACTED]' : v;
}
return clean;
}
function createMcpEngine(deps) {
const {
getStorageDataDir,
getDbPool,
isClientIpAllowed,
resolveInternalSecret,
decryptVaultSecret,
validateOutboundUrlAsync,
flushBuffer,
} = deps;
const state = {
enabled: false,
tokenHash: '',
tokenPreview: '',
allowedIps: '',
permissions: { ...DEFAULT_MCP_PERMISSIONS },
coolifyUrl: '',
coolifyToken: '',
coolifyAppUuid: '',
updatedAt: '',
};
function resolveSandboxRoot() {
const dataDir = path.resolve(
typeof getStorageDataDir === 'function'
? getStorageDataDir()
: path.resolve(process.cwd(), 'storage', 'data'),
);
if (path.basename(dataDir).toLowerCase() === 'data') {
return path.dirname(dataDir);
}
return dataDir;
}
async function resolveSafeStoragePath(rawRelPath, options = {}) {
const allowWriteRuntimeLogs = Boolean(options.allowWriteRuntimeLogs);
const requireExists = Boolean(options.requireExists);
const sandboxRoot = resolveSandboxRoot();
await fsp.mkdir(sandboxRoot, { recursive: true });
const sandboxReal = await fsp.realpath(sandboxRoot);
const rawStr = String(rawRelPath === undefined || rawRelPath === null ? '' : rawRelPath);
if (rawStr.includes('\0') || rawStr.includes('\\')) {
const err = new Error('Invalid characters in storage path.');
err.code = 'PATH_OUTSIDE_ROOT';
throw err;
}
const stripped = rawStr.trim().replace(/^\/+/, '');
const normalizedInput = stripped === '.' ? '' : stripped;
const segments = normalizedInput.split('/').filter(Boolean);
for (const seg of segments) {
if (seg === '..' || seg === '.') {
const err = new Error('Path traversal outside storage root is forbidden.');
err.code = 'PATH_OUTSIDE_ROOT';
throw err;
}
if (seg.toLowerCase().endsWith('.lock')) {
const err = new Error('Cooperative storage lockfiles (*.lock) are protected.');
err.code = 'LOCKFILE_PROTECTED';
throw err;
}
}
if (
!allowWriteRuntimeLogs &&
segments.length > 0 &&
segments[0].toLowerCase() === '.runtime-logs'
) {
const err = new Error(
'.runtime-logs directory is read-only via runtime/build log tools.',
);
err.code = 'PROTECTED_LOG_DIR';
throw err;
}
const resolvedTarget = segments.length
? path.resolve(sandboxRoot, ...segments)
: sandboxRoot;
if (
resolvedTarget !== sandboxRoot &&
!resolvedTarget.startsWith(`${sandboxRoot}${path.sep}`)
) {
const err = new Error('Resolved path escapes storage sandbox root.');
err.code = 'PATH_OUTSIDE_ROOT';
throw err;
}
// Walk segments to ensure no symlink ancestor or target escapes sandbox
let cursor = sandboxRoot;
for (let i = 0; i < segments.length; i += 1) {
cursor = path.join(cursor, segments[i]);
try {
const st = await fsp.lstat(cursor);
if (st.isSymbolicLink()) {
const err = new Error('Symlinks are forbidden inside storage sandbox.');
err.code = 'SYMLINK_FORBIDDEN';
throw err;
}
const real = await fsp.realpath(cursor);
if (real !== sandboxReal && !real.startsWith(`${sandboxReal}${path.sep}`)) {
const err = new Error('Resolved symlink escapes storage sandbox.');
err.code = 'PATH_OUTSIDE_ROOT';
throw err;
}
} catch (e) {
if (e && e.code === 'ENOENT') {
if (requireExists) {
const notFound = new Error(
`Storage path '${normalizedInput || '/'}' does not exist.`,
);
notFound.code = 'NOT_FOUND';
throw notFound;
}
break;
}
throw e;
}
}
return {
sandboxRoot,
sandboxReal,
relativePath: segments.join('/'),
fullPath: resolvedTarget,
};
}
function syncState(payload) {
if (!payload || typeof payload !== 'object') return;
if (payload.enabled !== undefined) {
state.enabled = Boolean(payload.enabled);
}
if (typeof payload.tokenHash === 'string') {
state.tokenHash = payload.tokenHash.trim().toLowerCase();
}
if (typeof payload.tokenPreview === 'string') {
state.tokenPreview = payload.tokenPreview.trim();
}
if (typeof payload.allowedIps === 'string') {
state.allowedIps = payload.allowedIps.trim();
}
if (payload.permissions !== undefined) {
state.permissions = normalizeMcpPermissions(payload.permissions, state.permissions);
}
if (typeof payload.coolifyUrl === 'string') {
state.coolifyUrl = payload.coolifyUrl.trim();
}
if (typeof payload.coolifyToken === 'string') {
state.coolifyToken = payload.coolifyToken.trim();
}
if (typeof payload.coolifyAppUuid === 'string') {
state.coolifyAppUuid = payload.coolifyAppUuid.trim();
}
if (typeof payload.updatedAt === 'string') {
state.updatedAt = payload.updatedAt;
}
}
async function hydrateFromDatabase(poolArg) {
const pool = poolArg || (typeof getDbPool === 'function' ? getDbPool() : null);
if (!pool || typeof pool.query !== 'function') return false;
try {
const res = await pool.query(
`SELECT enabled, token_hash, token_preview, allowed_ips, permissions_json,
coolify_url, coolify_token_enc, coolify_app_uuid, updated_at
FROM mcp_settings
WHERE id = 'default'`,
);
if (!res || !res.rowCount || res.rowCount === 0) {
return true;
}
const row = res.rows[0];
let parsedPerms = {};
try {
parsedPerms = JSON.parse(row.permissions_json || '{}');
} catch {
parsedPerms = {};
}
let decryptedCoolifyToken = '';
if (row.coolify_token_enc && typeof decryptVaultSecret === 'function') {
decryptedCoolifyToken = decryptVaultSecret(String(row.coolify_token_enc));
}
syncState({
enabled: Boolean(row.enabled),
tokenHash: String(row.token_hash || ''),
tokenPreview: String(row.token_preview || ''),
allowedIps: String(row.allowed_ips || ''),
permissions: normalizeMcpPermissions(parsedPerms, DEFAULT_MCP_PERMISSIONS),
coolifyUrl: String(row.coolify_url || ''),
coolifyToken: decryptedCoolifyToken,
coolifyAppUuid: String(row.coolify_app_uuid || ''),
updatedAt:
row.updated_at instanceof Date
? row.updated_at.toISOString()
: String(row.updated_at || ''),
});
return true;
} catch {
return false;
}
}
async function recordMcpAudit({ action, target, ipAddress, metadata }) {
const entry = {
id: `aud_${Date.now()}_${crypto.randomBytes(6).toString('hex')}`,
actorEmail: 'mcp-agent',
actorRole: 'mcp',
action,
target: String(target || 'mcp').slice(0, 256),
ipAddress: String(ipAddress || '').slice(0, 128),
metadata: sanitizeAuditMeta(metadata),
createdAt: new Date().toISOString(),
};
const pool = typeof getDbPool === 'function' ? getDbPool() : null;
if (pool && typeof pool.query === 'function') {
try {
await pool.query(
`INSERT INTO admin_audit_logs (
id, actor_email, actor_role, action, target, ip_address, metadata_json, created_at
)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8::timestamptz)`,
[
entry.id,
entry.actorEmail,
entry.actorRole,
entry.action,
entry.target,
entry.ipAddress,
JSON.stringify(entry.metadata),
entry.createdAt,
],
);
return entry;
} catch {
// Fall through to in-memory buffer only if DB insert failed
}
}
if (!Array.isArray(globalThis.__dataStackAuditLogs)) {
globalThis.__dataStackAuditLogs = [];
}
globalThis.__dataStackAuditLogs.unshift(entry);
if (globalThis.__dataStackAuditLogs.length > MAX_IN_MEMORY_AUDIT_LOGS) {
globalThis.__dataStackAuditLogs.length = MAX_IN_MEMORY_AUDIT_LOGS;
}
return entry;
}
async function callWebInternalMcp(action, params, actorIp) {
const secret =
typeof resolveInternalSecret === 'function' ? resolveInternalSecret() : '';
if (!secret) {
const err = new Error('Internal MCP bridge secret is not configured.');
err.code = 'MCP_BRIDGE_UNAUTHORIZED';
throw err;
}
const baseUrl = (
process.env.WEB_INTERNAL_URL ||
`http://127.0.0.1:${Number(process.env.PORT) || 3000}`
).replace(/\/+$/, '');
const res = await fetch(`${baseUrl}/api/internal/mcp`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-datastack-internal-secret': secret,
},
body: JSON.stringify({ action, params: params || {}, actorIp }),
signal: AbortSignal.timeout(10000),
});
const data = await res.json().catch(() => ({}));
if (!res.ok) {
const err = new Error(
(data && data.error) || `Internal MCP bridge returned HTTP ${res.status}`,
);
err.code = (data && data.code) || 'MCP_BRIDGE_ERROR';
throw err;
}
return data;
}
async function fetchCoolifyLogs(lines = 120) {
if (!state.coolifyUrl || !state.coolifyToken || !state.coolifyAppUuid) {
return {
coolifyConfigured: false,
note: 'Optional Coolify log integration is not configured in Admin MCP Settings.',
};
}
const endpoint = `${state.coolifyUrl.replace(/\/+$/, '')}/api/v1/applications/${encodeURIComponent(
state.coolifyAppUuid,
)}/logs?lines=${Math.min(500, Math.max(1, Number(lines) || 120))}`;
if (typeof validateOutboundUrlAsync === 'function') {
const ssrf = await validateOutboundUrlAsync(endpoint);
if (!ssrf.allowed) {
const err = new Error(ssrf.error || 'Coolify URL blocked by SSRF guard.');
err.code = ssrf.code || 'SSRF_BLOCKED_HOST';
throw err;
}
}
const res = await fetch(endpoint, {
method: 'GET',
headers: {
Authorization: `Bearer ${state.coolifyToken}`,
Accept: 'application/json',
},
redirect: 'manual',
signal: AbortSignal.timeout(6000),
});
if (res.status >= 300 && res.status < 400) {
const err = new Error(`Coolify endpoint attempted HTTP ${res.status} redirect.`);
err.code = 'SSRF_BLOCKED_HOST';
throw err;
}
const rawText = await res.text();
const scrubbed = scrubSensitiveLogText(rawText);
if (!res.ok) {
return {
coolifyConfigured: true,
ok: false,
status: res.status,
error: scrubbed.slice(0, 500),
};
}
let parsed = null;
try {
parsed = JSON.parse(scrubbed);
} catch {
parsed = { raw: scrubbed.slice(0, 64 * 1024) };
}
return {
coolifyConfigured: true,
ok: true,
data: parsed,
};
}
function formatToolSuccess(data) {
return {
content: [
{
type: 'text',
text: JSON.stringify(data, null, 2),
},
],
};
}
function formatToolError(code, message, extra = {}) {
return {
isError: true,
content: [
{
type: 'text',
text: JSON.stringify(
{
ok: false,
code: code || 'MCP_TOOL_ERROR',
error: message,
...extra,
},
null,
2,
),
},
],
};
}
function createScopedMcpServer(actorIp) {
const server = new McpServer(
{
name: 'datastack-mcp',
version: '2.2.0',
},
{
capabilities: {
tools: {},
},
},
);
const registerGuardedTool = (name, config, permissionKey, handler) => {
server.registerTool(name, config, async (args) => {
if (!state.permissions[permissionKey]) {
await recordMcpAudit({
action: 'MCP_TOOL_DENIED',
target: name,
ipAddress: actorIp,
metadata: {
permission: permissionKey,
code: 'MCP_PERMISSION_DENIED',
},
});
return formatToolError(
'MCP_PERMISSION_DENIED',
`Permission '${permissionKey}' is disabled in Admin MCP Settings.`,
{ permission: permissionKey, tool: name },
);
}
try {
const result = await handler(args || {});
await recordMcpAudit({
action: 'MCP_TOOL_CALLED',
target: name,
ipAddress: actorIp,
metadata: { permission: permissionKey },
});
return formatToolSuccess(result);
} catch (err) {
const errCode = (err && err.code) || 'MCP_TOOL_ERROR';
const errMsg = err instanceof Error ? err.message : String(err);
await recordMcpAudit({
action: 'MCP_TOOL_CALLED',
target: name,
ipAddress: actorIp,
metadata: {
permission: permissionKey,
errorCode: errCode,
},
});
return formatToolError(errCode, errMsg, { tool: name });
}
});
};
// 1. Metrics & Health
registerGuardedTool(
'datastack_metrics_health',
{
description:
'Inspect live DataStack dashboard metrics, active Socket.IO connections, buffer queue depth, PostgreSQL/Redis status, and VPS disk usage.',
inputSchema: {},
},
'metrics_health_read',
async () => callWebInternalMcp('metrics_get', {}, actorIp),
);
// 2. Runtime Logs (Web + Ingestion)
registerGuardedTool(
'datastack_runtime_logs',
{
description:
'Read rotating stdout/stderr runtime logs for Next.js Web (Port 3000) and Ingestion (Port 4000) with optional service, level, and search filters.',
inputSchema: {
service: z.enum(['all', 'web', 'ingestion']).optional(),
lines: z.number().int().min(1).max(500).optional(),
level: z.enum(['all', 'info', 'error']).optional(),
search: z.string().max(200).optional(),
},
},
'runtime_logs_read',
async (args) => callWebInternalMcp('runtime_logs_read', args, actorIp),
);
// 3. Build & Optional Coolify Logs
registerGuardedTool(
'datastack_build_logs',
{
description:
'Read captured Next.js standalone build logs and build metadata, and optionally fetch Coolify deployment logs when configured.',
inputSchema: {
lines: z.number().int().min(1).max(500).optional(),
search: z.string().max(200).optional(),
includeCoolify: z.boolean().optional(),
},
},
'build_logs_read',
async (args) => {
const buildRes = await callWebInternalMcp(
'build_logs_read',
{ lines: args.lines, search: args.search },
actorIp,
);
if (args.includeCoolify) {
const coolify = await fetchCoolifyLogs(args.lines || 120);
return { ...buildRes, coolify };
}
return buildRes;
},
);
// 4. Admin Audit Logs
registerGuardedTool(
'datastack_audit_logs',
{
description:
'Query immutable Admin Console, RBAC, Client, Storage, and MCP governance audit logs.',
inputSchema: {
limit: z.number().int().min(1).max(200).optional(),
action: z.string().max(100).optional(),
actorEmail: z.string().max(160).optional(),
search: z.string().max(200).optional(),
},
},
'audit_logs_read',
async (args) => callWebInternalMcp('audit_query', args, actorIp),
);
// 5. Ingested Events Query
registerGuardedTool(
'datastack_events_query',
{
description:
'Query buffered in-flight events and stored CSV/CSV.GZ telemetry partitions across clients or date ranges.',
inputSchema: {
clientId: z.string().max(120).optional(),
search: z.string().max(200).optional(),
from: z.string().max(32).optional(),
to: z.string().max(32).optional(),
limit: z.number().int().min(1).max(100).optional(),
},
},
'ingestion_events_read',
async (args) => callWebInternalMcp('data_query', args, actorIp),
);
// 6. Clients Read
registerGuardedTool(
'datastack_clients_list',
{
description:
'List all registered SDK clients or inspect a single client by clientId (secrets are redacted).',
inputSchema: {
clientId: z.string().max(120).optional(),
},
},
'clients_read',
async (args) => {
if (args.clientId) {
return callWebInternalMcp(
'clients_get',
{ clientId: args.clientId },
actorIp,
);
}
return callWebInternalMcp('clients_list', {}, actorIp);
},
);
// 7. Clients Create
registerGuardedTool(
'datastack_clients_create',
{
description: 'Register a new SDK client and issue its initial client JWT token.',
inputSchema: {
clientId: z.string().min(1).max(120),
name: z.string().min(1).max(120),
rateLimit: z.number().int().min(1).max(100000).optional(),
storageQuotaMb: z.number().int().min(0).max(1048576).optional(),
allowedIps: z.string().max(2048).optional(),
expiresAt: z.string().max(64).nullable().optional(),
},
},
'clients_create',
async (args) => callWebInternalMcp('clients_create', args, actorIp),
);
// 8. Clients Update
registerGuardedTool(
'datastack_clients_update',
{
description:
'Update an existing SDK client (name, rateLimit, storageQuotaMb, allowedIps, expiresAt, or status).',
inputSchema: {
clientId: z.string().min(1).max(120),
name: z.string().min(1).max(120).optional(),
rateLimit: z.number().int().min(1).max(100000).optional(),
storageQuotaMb: z.number().int().min(0).max(1048576).optional(),
allowedIps: z.string().max(2048).optional(),
expiresAt: z.string().max(64).nullable().optional(),
status: z.enum(['active', 'revoked']).optional(),
},
},
'clients_update',
async (args) => callWebInternalMcp('clients_update', args, actorIp),
);
// 9. Clients Rotate / Revoke / Delete
registerGuardedTool(
'datastack_clients_manage_token',
{
description:
'Rotate a client JWT token, revoke client access, or permanently delete a client (optionally purging CSV files).',
inputSchema: {
action: z.enum(['rotate_token', 'revoke', 'delete']),
clientId: z.string().min(1).max(120),
purgeFiles: z.boolean().optional(),
},
},
'clients_revoke_delete',
async (args) => {
if (args.action === 'rotate_token') {
return callWebInternalMcp(
'clients_rotate_token',
{ clientId: args.clientId },
actorIp,
);
}
if (args.action === 'revoke') {
return callWebInternalMcp(
'clients_revoke',
{ clientId: args.clientId },
actorIp,
);
}
return callWebInternalMcp(
'clients_delete',
{ clientId: args.clientId, purgeFiles: args.purgeFiles === true },
actorIp,
);
},
);
// 10. Files List / Inspect Lines
registerGuardedTool(
'datastack_files_list',
{
description:
'List directories or inspect bounded text lines inside /app/storage (symlinks and *.lock files are blocked).',
inputSchema: {
path: z.string().max(512).optional(),
readLines: z.boolean().optional(),
offsetLines: z.number().int().min(0).max(1000000).optional(),
limitLines: z.number().int().min(1).max(500).optional(),
},
},
'files_list_read',
async (args) => {
const target = await resolveSafeStoragePath(args.path || '', {
allowWriteRuntimeLogs: true,
requireExists: true,
});
const stat = await fsp.lstat(target.fullPath);
if (stat.isDirectory()) {
const rawNames = await fsp.readdir(target.fullPath);
const entries = [];
for (const name of rawNames.sort()) {
if (name.toLowerCase().endsWith('.lock')) continue;
const childPath = path.join(target.fullPath, name);
const childStat = await fsp.lstat(childPath).catch(() => null);
if (!childStat || childStat.isSymbolicLink()) continue;
entries.push({
name,
path: target.relativePath ? `${target.relativePath}/${name}` : name,
type: childStat.isDirectory() ? 'directory' : 'file',
sizeBytes: childStat.isFile() ? childStat.size : 0,
modifiedAt: childStat.mtime.toISOString(),
});
}
return {
ok: true,
kind: 'directory',
path: target.relativePath || '/',
entries,
count: entries.length,
};
}
if (!stat.isFile()) {
const err = new Error('Target is not a regular file or directory.');
err.code = 'INVALID_FILE_TYPE';
throw err;
}
if (!args.readLines) {
return {
ok: true,
kind: 'file',
path: target.relativePath,
sizeBytes: stat.size,
modifiedAt: stat.mtime.toISOString(),
};
}
const bytesToRead = Math.min(stat.size, MAX_READ_BYTES);
const fh = await fsp.open(target.fullPath, 'r');
try {
const buf = Buffer.allocUnsafe(bytesToRead);
const { bytesRead } = await fh.read(buf, 0, bytesToRead, 0);
const text = buf.subarray(0, bytesRead).toString('utf8');
const allLines = text.split(/\r?\n/);
const offset = Math.max(0, Number(args.offsetLines) || 0);
const limit = Math.min(500, Math.max(1, Number(args.limitLines) || 120));
return {
ok: true,
kind: 'file_lines',
path: target.relativePath,
totalSizeBytes: stat.size,
truncatedToBytes: bytesToRead < stat.size ? bytesToRead : null,
offsetLines: offset,
lines: allLines.slice(offset, offset + limit),
totalLinesInWindow: allLines.length,
};
} finally {
await fh.close();
}
},
);
// 11. Files Download Chunk
registerGuardedTool(
'datastack_files_download',
{
description:
'Download a bounded utf8 or base64 byte chunk from a non-locked file inside /app/storage.',
inputSchema: {
path: z.string().min(1).max(512),
offsetBytes: z.number().int().min(0).optional(),
maxBytes: z.number().int().min(1).max(MAX_READ_BYTES).optional(),
encoding: z.enum(['utf8', 'base64']).optional(),
},
},
'files_download',
async (args) => {
const target = await resolveSafeStoragePath(args.path, {
allowWriteRuntimeLogs: true,
requireExists: true,
});
const stat = await fsp.lstat(target.fullPath);
if (!stat.isFile()) {
const err = new Error('Target path is not a regular file.');
err.code = 'INVALID_FILE_TYPE';
throw err;
}
const offset = Math.min(stat.size, Math.max(0, Number(args.offsetBytes) || 0));
const maxBytes = Math.min(
MAX_READ_BYTES,
Math.max(1, Number(args.maxBytes) || 131072),
);
const remaining = Math.max(0, stat.size - offset);
const length = Math.min(remaining, maxBytes);
const encoding = args.encoding === 'base64' ? 'base64' : 'utf8';
const fh = await fsp.open(target.fullPath, 'r');
try {
const buf = Buffer.allocUnsafe(length);
const { bytesRead } = length > 0
? await fh.read(buf, 0, length, offset)
: { bytesRead: 0 };
const slice = buf.subarray(0, bytesRead);
return {
ok: true,
path: target.relativePath,
encoding,
offsetBytes: offset,
bytesRead,
totalSizeBytes: stat.size,
hasMore: offset + bytesRead < stat.size,
content: slice.toString(encoding),
};
} finally {
await fh.close();
}
},
);
// 12. Files Upload / Create
registerGuardedTool(
'datastack_files_upload',
{
description:
'Create or upload a file inside /app/storage (respecting *.lock and .runtime-logs write protection).',
inputSchema: {
path: z.string().min(1).max(512),
content: z.string(),
encoding: z.enum(['utf8', 'base64']).optional(),
overwrite: z.boolean().optional(),
},
},
'files_upload_create',
async (args) => {
const encoding = args.encoding === 'base64' ? 'base64' : 'utf8';
const dataBuf = Buffer.from(args.content, encoding);
if (dataBuf.length > MAX_WRITE_BYTES) {
const err = new Error(
`Upload exceeds ${MAX_WRITE_BYTES} bytes single-call safety limit.`,
);
err.code = 'PAYLOAD_TOO_LARGE';
throw err;
}
const target = await resolveSafeStoragePath(args.path, {
allowWriteRuntimeLogs: false,
requireExists: false,
});
if (!target.relativePath) {
const err = new Error('Target file path must not be root directory.');
err.code = 'VALIDATION_ERROR';
throw err;
}
const lockSibling = `${target.fullPath}.lock`;
if (fs.existsSync(lockSibling)) {
const err = new Error('File is currently locked by storage writer.');
err.code = 'LOCKFILE_PROTECTED';
throw err;
}
const existingStat = await fsp.lstat(target.fullPath).catch(() => null);
if (existingStat) {
if (existingStat.isDirectory() || existingStat.isSymbolicLink()) {
const err = new Error('Cannot overwrite directory or symlink.');
err.code = 'INVALID_FILE_TYPE';
throw err;
}
if (!args.overwrite) {
const err = new Error(
`File '${target.relativePath}' already exists and overwrite=false.`,
);
err.code = 'FILE_EXISTS';
throw err;
}
}
await fsp.mkdir(path.dirname(target.fullPath), { recursive: true });
await fsp.writeFile(target.fullPath, dataBuf);
return {
ok: true,
path: target.relativePath,
bytesWritten: dataBuf.length,
overwritten: Boolean(existingStat),
};
},
);
// 13. Files Edit (Targeted Search & Replace)
registerGuardedTool(
'datastack_files_edit',
{
description:
'Perform targeted search/replace editing on a regular non-locked UTF-8 file inside /app/storage.',
inputSchema: {
path: z.string().min(1).max(512),
search: z.string().min(1),
replace: z.string(),
replaceAll: z.boolean().optional(),
},
},
'files_edit',
async (args) => {
const target = await resolveSafeStoragePath(args.path, {
allowWriteRuntimeLogs: false,
requireExists: true,
});
const stat = await fsp.lstat(target.fullPath);
if (!stat.isFile()) {
const err = new Error('Target path is not a regular file.');
err.code = 'INVALID_FILE_TYPE';
throw err;
}
if (stat.size > MAX_WRITE_BYTES) {
const err = new Error(
`File exceeds ${MAX_WRITE_BYTES} bytes safe inline edit limit.`,
);
err.code = 'PAYLOAD_TOO_LARGE';
throw err;
}
const lockSibling = `${target.fullPath}.lock`;
if (fs.existsSync(lockSibling)) {
const err = new Error('File is currently locked by storage writer.');
err.code = 'LOCKFILE_PROTECTED';
throw err;
}
const current = await fsp.readFile(target.fullPath, 'utf8');
if (!current.includes(args.search)) {
const err = new Error('Search text was not found in target file.');
err.code = 'SEARCH_NOT_FOUND';
throw err;
}
let occurrences = 0;
let updated;
if (args.replaceAll) {
const parts = current.split(args.search);
occurrences = parts.length - 1;
updated = parts.join(args.replace);
} else {
occurrences = 1;
const idx = current.indexOf(args.search);
updated =
current.slice(0, idx) +
args.replace +
current.slice(idx + args.search.length);
}
if (Buffer.byteLength(updated, 'utf8') > MAX_WRITE_BYTES) {
const err = new Error('Edited content exceeds maximum safe file size.');
err.code = 'PAYLOAD_TOO_LARGE';
throw err;
}
await fsp.writeFile(target.fullPath, updated, 'utf8');
return {
ok: true,
path: target.relativePath,
replacements: occurrences,
newSizeBytes: Buffer.byteLength(updated, 'utf8'),
};
},
);
// 14. Files Delete
registerGuardedTool(
'datastack_files_delete',
{
description:
'Delete a regular non-locked file inside /app/storage (directories, symlinks, *.lock, and .runtime-logs are protected).',
inputSchema: {
path: z.string().min(1).max(512),
},
},
'files_delete',
async (args) => {
const target = await resolveSafeStoragePath(args.path, {
allowWriteRuntimeLogs: false,
requireExists: true,
});
if (!target.relativePath) {
const err = new Error('Cannot delete storage root.');
err.code = 'PATH_OUTSIDE_ROOT';
throw err;
}
const stat = await fsp.lstat(target.fullPath);
if (!stat.isFile()) {
const err = new Error('Only regular files may be deleted via MCP.');
err.code = 'INVALID_FILE_TYPE';
throw err;
}
const lockSibling = `${target.fullPath}.lock`;
if (fs.existsSync(lockSibling)) {
const err = new Error('File is currently locked by storage writer.');
err.code = 'LOCKFILE_PROTECTED';
throw err;
}
await fsp.unlink(target.fullPath);
return {
ok: true,
deletedPath: target.relativePath,
};
},
);
// 15. Settings Read (Masked)
registerGuardedTool(
'datastack_settings_read',
{
description:
'Read DataStack public runtime settings (all secrets and tokens remain masked).',
inputSchema: {},
},
'settings_read',
async () => callWebInternalMcp('settings_get', {}, actorIp),
);
// 16. Settings Write (Allowlisted Non-Secret Fields Only)
registerGuardedTool(
'datastack_settings_update',
{
description:
'Update safe allowlisted DataStack runtime settings (rate limits, batch thresholds, rotation, retention, non-secret webhook/S3/Prometheus flags).',
inputSchema: {
maxEventsPerSec: z.number().int().min(1).max(100000).optional(),
maxPayloadSizeKb: z.number().int().min(1).max(10240).optional(),
batchFlushThreshold: z.number().int().min(1).max(50000).optional(),
batchFlushIntervalMs: z.number().int().min(100).max(60000).optional(),
fileRotationMb: z.number().int().min(1).max(2048).optional(),
enableIdempotency: z.boolean().optional(),
autoPruneDays: z.number().int().min(0).max(3650).optional(),
compressAfterDays: z.number().int().min(0).max(3650).optional(),
diskPauseThresholdPct: z.number().int().min(0).max(99).optional(),
enableWebhookAlerts: z.boolean().optional(),
webhookUrl: z.string().max(1024).optional(),
webhookCooldownSec: z.number().int().min(10).max(86400).optional(),
enableS3Backup: z.boolean().optional(),
s3Endpoint: z.string().max(512).optional(),
s3Region: z.string().max(64).optional(),
s3Bucket: z.string().max(128).optional(),
s3Prefix: z.string().max(256).optional(),
s3AccessKeyId: z.string().max(256).optional(),
enablePrometheusMetrics: z.boolean().optional(),
},
},
'settings_write',
async (args) => callWebInternalMcp('settings_update', args, actorIp),
);
// 17. Storage Stats / Flush / S3 Archive
registerGuardedTool(
'datastack_storage_maintenance',
{
description:
'Inspect storage stats, trigger an immediate ingestion+web buffer flush to CSV, or trigger an S3 cold archive run.',
inputSchema: {
action: z.enum(['stats', 'flush', 's3_archive']),
pruneAfterUpload: z.boolean().optional(),
},
},
'storage_maintenance',
async (args) => {
if (args.action === 'stats') {
return callWebInternalMcp('storage_stats', {}, actorIp);
}
if (args.action === 'flush') {
let ingestionFlushed = 0;
if (typeof flushBuffer === 'function') {
const ing = await flushBuffer({ waitMs: 2500, throwOnLockTimeout: true });
ingestionFlushed = ing ? Number(ing.written) || 0 : 0;
}
const web = await callWebInternalMcp('storage_flush', {}, actorIp);
return {
...web,
ingestionFlushed,
};
}
return callWebInternalMcp(
'storage_s3_archive',
{ pruneAfterUpload: args.pruneAfterUpload === true },
actorIp,
);
},
);
return server;
}
async function authenticateRequest(req) {
if (!state.enabled || !state.tokenHash || state.tokenHash.length !== 64) {
return {
allowed: false,
status: 503,
code: 'MCP_DISABLED',
error: 'MCP Server is currently disabled in Admin Console Settings.',
};
}
const clientIp = extractMcpClientIp(req);
if (
state.allowedIps &&
typeof isClientIpAllowed === 'function' &&
!isClientIpAllowed(clientIp, state.allowedIps)
) {
await recordMcpAudit({
action: 'MCP_TOOL_DENIED',
target: 'mcp_ip_allowlist',
ipAddress: clientIp,
metadata: { code: 'MCP_IP_FORBIDDEN' },
});
return {
allowed: false,
status: 403,
code: 'MCP_IP_FORBIDDEN',
error: `Client IP '${clientIp}' is not in the MCP allowed IP/CIDR list.`,
};
}
const authHeader =
(req.headers && (req.headers.authorization || req.headers.Authorization)) ||
'';
const match = String(authHeader).match(/^Bearer\s+(.+)$/i);
const presented = match ? match[1].trim() : '';
if (!presented || !verifyMcpBearerTokenHash(presented, state.tokenHash)) {
await recordMcpAudit({
action: 'MCP_TOOL_DENIED',
target: 'mcp_auth',
ipAddress: clientIp,
metadata: { code: 'MCP_UNAUTHORIZED' },
});
return {
allowed: false,
status: 401,
code: 'MCP_UNAUTHORIZED',
error: 'Missing or invalid MCP Bearer token.',
};
}
return { allowed: true, clientIp };
}
async function handleHttpRequest(req, res) {
res.setHeader('Cache-Control', 'no-store, private');
const auth = await authenticateRequest(req);
if (!auth.allowed) {
return res.status(auth.status).json({
jsonrpc: '2.0',
error: {
code: auth.status === 401 ? -32001 : auth.status === 403 ? -32003 : -32000,
message: auth.error,
data: { code: auth.code },
},
id: null,
});
}
// Ensure simple HTTP JSON-RPC clients that omit text/event-stream still succeed cleanly
const method = String(req.method || 'POST').toUpperCase();
const rawAccept = String((req.headers && req.headers.accept) || '');
if (
method === 'POST' &&
(!rawAccept.includes('application/json') ||
!rawAccept.includes('text/event-stream'))
) {
req.headers.accept = 'application/json, text/event-stream';
}
const mcpServer = createScopedMcpServer(auth.clientIp);
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
});
res.on('close', () => {
void transport.close().catch(() => undefined);
void mcpServer.close().catch(() => undefined);
});
try {
await mcpServer.connect(transport);
await transport.handleRequest(
req,
res,
method === 'POST' ? req.body : undefined,
);
} catch (err) {
if (!res.headersSent) {
res.status(500).json({
jsonrpc: '2.0',
error: {
code: -32603,
message:
err instanceof Error ? err.message : 'Internal MCP server error',
},
id: null,
});
}
}
}
function getStateSnapshot() {
return {
...state,
coolifyToken: state.coolifyToken ? '[REDACTED]' : '',
permissions: { ...state.permissions },
};
}
function resetForTests() {
state.enabled = false;
state.tokenHash = '';
state.tokenPreview = '';
state.allowedIps = '';
state.permissions = { ...DEFAULT_MCP_PERMISSIONS };
state.coolifyUrl = '';
state.coolifyToken = '';
state.coolifyAppUuid = '';
state.updatedAt = '';
}
return {
syncState,
hydrateFromDatabase,
authenticateRequest,
handleHttpRequest,
getStateSnapshot,
resetForTests,
resolveSafeStoragePath,
MCP_PERMISSION_KEYS,
};
}
module.exports = {
createMcpEngine,
hashMcpToken,
verifyMcpBearerTokenHash,
MCP_PERMISSION_KEYS,
DEFAULT_MCP_PERMISSIONS,
};