feat(mcp): реализовать серверную часть MCP, адаптеры, сервисы и скрипты приёмки

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
This commit is contained in:
DenozordecandClaude Sonnet 5.5 committed 2026-11-15 20:36:13 +07:00
1 parent 7380f18f15
commit 18c0a52171
1565 files changed
+175806 -5772

No files matched your search

@@ -0,0 +1,14 @@
import { closePool } from "../db/index.js"
import { completePendingSystemDatabaseRestore } from "../services/system-database-restore-recovery.js"
try {
const [, , operationId, appliedJournalSha256, extra] = process.argv
if (!operationId || !appliedJournalSha256 || extra !== undefined) {
throw new Error("Использование: db:complete-restore <operation-id> <sha256-журнала>")
}
await completePendingSystemDatabaseRestore(operationId, appliedJournalSha256)
console.log("Карантин PostgreSQL снят для подтверждённого восстановления")
} catch (error) {
console.error(error instanceof Error ? error.message : "Снятие карантина PostgreSQL не подтверждено")
process.exitCode = 1
} finally { await closePool() }
@@ -0,0 +1,10 @@
import { closePool } from "../db/index.js"
import { inspectSystemDatabaseRestoreCheckpoint } from "../services/system-database-restore-inspection.js"
try {
if (process.argv.length !== 2) throw new Error()
console.log(JSON.stringify(await inspectSystemDatabaseRestoreCheckpoint()))
} catch {
console.error("Не удалось сверить контрольную точку PostgreSQL. Сохраните журнал и исходные файлы для проверки.")
process.exitCode = 1
} finally { await closePool() }
@@ -0,0 +1,34 @@
import { env } from "../config.js"
import { assertRuntimeDatabaseActivationCurrent, closePool, pool } from "../db/index.js"
import { captureRuntimeDatabaseSchema } from "../db/database-runtime-schema.js"
import { captureRuntimeRestoreData } from "../db/database-restore-data.js"
import { withSystemDatabaseOperationLock } from "../db/operation-lock.js"
import { assertDatabaseRestoreQuarantineOpen, databaseRestoreQuarantineEnabled } from "../db/database-restore-quarantine.js"
import { mcpStateDirectory } from "../modules/mcp/security.js"
import { assertDatabaseMaintenanceStartup } from "../services/database-maintenance-startup.js"
try {
if (!process.env.DATABASE_RUNTIME_REQUEST_FILE) throw new Error("Для сверки схемы требуется утверждённый источник PostgreSQL")
const directory = mcpStateDirectory()
await assertDatabaseMaintenanceStartup(directory, env.DATABASE_URL)
const result = await withSystemDatabaseOperationLock(() => pool.connect(), async (client, discard) => {
await assertDatabaseMaintenanceStartup(directory, env.DATABASE_URL)
if (databaseRestoreQuarantineEnabled()) await assertDatabaseRestoreQuarantineOpen(client)
assertRuntimeDatabaseActivationCurrent()
if (process.argv.includes("--data")) {
const passwordFile = process.env.DATABASE_ARCHIVE_PASSWORD_FILE
if (process.env.DATABASE_RUNTIME_WRITER_APPROVAL_FILE !== undefined && !passwordFile) {
throw new Error("Для сверки данных требуется файл пароля роли архивирования PostgreSQL")
}
const snapshot = passwordFile
? await (await import("../services/database-capture-inspection.js")).inspectProtectedDatabaseData(client, discard, passwordFile)
: await captureRuntimeRestoreData(client, discard)
assertRuntimeDatabaseActivationCurrent()
return { format: snapshot.format, schemaSha256: snapshot.schemaSha256, dataSha256: snapshot.sha256 }
}
const snapshot = await captureRuntimeDatabaseSchema(client, discard)
assertRuntimeDatabaseActivationCurrent()
return { format: snapshot.format, schemaSha256: snapshot.sha256, serverVersion: snapshot.serverVersion }
})
console.log(JSON.stringify(result))
} finally { await closePool() }
+45
View File
@@ -0,0 +1,45 @@
import assert from "node:assert/strict"
import { readFile, readdir } from "node:fs/promises"
import { listActions } from "../modules/mcp/actions.js"
import { coverageSchema, routeKey } from "../modules/mcp/coverage.js"
const coverage = coverageSchema.parse(JSON.parse(await readFile(new URL("../../mcp-coverage.json", import.meta.url), "utf8")))
const descriptors = listActions().map(action => action.operation)
assert.equal(new Set(descriptors.map(action => action.toolName)).size, descriptors.length, "Duplicate tool name")
const routesByOperation = new Map<string, string[]>()
for (const route of coverage.routes) {
for (const id of route.operations) {
const routes = routesByOperation.get(id) ?? []
routes.push(routeKey(route))
routesByOperation.set(id, routes)
}
}
const auditDirectory = new URL("../../../docs/", import.meta.url)
const auditFiles = (await readdir(auditDirectory)).filter(name => /^mcp-.*-call-audit-\d{8}\.md$/.test(name)).sort()
const auditsByTool = new Map<string, string[]>()
for (const name of auditFiles) {
const source = await readFile(new URL(name, auditDirectory), "utf8")
const tools = new Set<string>()
for (const line of source.split(/\r?\n/)) {
if (!line.startsWith("|")) continue
// The owning call must occur in the first column or follow the step number.
const [, first, second] = line.split("|")
const toolColumn = /^\s*\d+\s*$/.test(first) ? second : first
const match = /\x60(mm_[a-z0-9_]+)(?=[({\x60])/.exec(toolColumn ?? "")
if (match) tools.add(match[1])
}
for (const tool of tools) {
const files = auditsByTool.get(tool) ?? []
files.push(name)
auditsByTool.set(tool, files)
}
}
const registeredTools = new Set(descriptors.map(action => action.toolName))
for (const tool of auditsByTool.keys()) assert(registeredTools.has(tool), `Audit refers to an unregistered tool: ${tool}`)
const rows = descriptors.map(({ id, toolName, version, section, effect, implementation }) => ({
id, toolName, version, section, effect, implementation, managerRestRoutes: (routesByOperation.get(id) ?? []).sort(),
callAuditReferences: auditsByTool.get(toolName) ?? [],
})).sort((left, right) => left.section.localeCompare(right.section) || left.toolName.localeCompare(right.toolName))
// Output is a work list, not evidence of native RouterOS compatibility or a successful invocation.
console.log(JSON.stringify(rows, null, 2))
+14
View File
@@ -0,0 +1,14 @@
import { readFile, writeFile } from "node:fs/promises"
import { collectApplicationRoutes, coverageSchema, routeKey, type CoverageEntry } from "../modules/mcp/coverage.js"
if (process.argv[2] !== "--update") throw new Error("Explicit --update required; newly discovered routes remain pending")
const file = new URL("../../mcp-coverage.json", import.meta.url)
const previous = await readFile(file, "utf8").then(text => coverageSchema.parse(JSON.parse(text)).routes, error => { if (error.code === "ENOENT") return []; throw error })
const known = new Map(previous.map(entry => [routeKey(entry), entry]))
const routes: CoverageEntry[] = (await collectApplicationRoutes()).map(route => known.get(routeKey(route)) ?? {
...route, operations: [],
status: /^(?:\/api\/(?:mcp(?:\/|$)|auth\/config$)|\/mcp$|\/oauth\/|\/\.well-known\/|\/_internal\/mcp\/|\/health$)/.test(route.path) ? "excluded" : "pending",
reason: /^(?:\/api\/mcp|\/mcp$|\/oauth\/|\/\.well-known\/|\/_internal\/mcp\/)/.test(route.path) ? "Управление самим MCP, транспорт или машинная авторизация: отдельного AI-инструмента нет." : ["/health", "/api/auth/config"].includes(route.path) ? "Bootstrap/health авторизации интерфейса; бизнес-операция MCP отсутствует." : "Нужен точный сервисный MCP-адаптер и проверка зависимостей; native-инструменты не объявляются эквивалентом этого REST-сценария.",
})
await writeFile(file, JSON.stringify(coverageSchema.parse({ version: 1, routes }), null, 2) + "\n")
console.log(routes.map(routeKey).join("\n"))
+43
View File
@@ -0,0 +1,43 @@
import { AsyncLocalStorage } from "node:async_hooks"
import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client"
import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio"
import { createStdioSdkTerminalGuard, StdioSdkBudgetedMcpServer } from "../modules/mcp/stdio-terminal-budget.js"
// Deliberately does not import dotenv/config: stdout belongs exclusively to MCP.
const endpoint = process.env.MCP_URL, token = process.env.MCP_TOKEN
if (!endpoint || !token) { process.stderr.write("Укажите MCP_URL и MCP_TOKEN\n"); process.exit(1) }
const url = new URL(endpoint)
if (url.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) throw new Error("Удалённый MCP требует HTTPS")
const serverInfo = Object.freeze({ name: "MikrotikManager-stdio", version: "1.0.0" })
const remote = new Client(serverInfo)
const followSignal = new AsyncLocalStorage<AbortSignal>()
await remote.connect(new StreamableHTTPClientTransport(url, {
requestInit: { headers: { authorization: "Bearer " + token } },
fetch: (input, init) => {
const signal = followSignal.getStore()
if (!signal) return fetch(input, init)
return fetch(input, { ...init, signal: init?.signal ? AbortSignal.any([init.signal, signal]) : signal })
},
}))
const guard = createStdioSdkTerminalGuard(serverInfo)
const wire = new StdioServerTransport()
guard.decorateWire(wire)
const handle = serveStdio(async () => {
const server = new StdioSdkBudgetedMcpServer(guard)
server.server.registerCapabilities({ tools: {} })
// The remote server supplies current policy and validates tool arguments.
server.server.setRequestHandler("tools/list", ({ params }, context) =>
remote.listTools({ cursor: params?.cursor }, { signal: context.mcpReq.signal }))
server.server.setRequestHandler("tools/call", ({ params }, context) => {
guard.protectCallback(context.mcpReq.id)
const request = { name: params.name, arguments: params.arguments }
// Follow owns a cancellable upstream read. Mutation outcomes still need their receipt.
return params.name === "mm_logs_follow"
? followSignal.run(context.mcpReq.signal, () => remote.callTool(request))
: remote.callTool(request)
})
return server
}, { transport: wire, onerror: () => process.stderr.write("Ошибка связи с MCP; проверьте доступ и журнал обращений\n") })
process.once("SIGTERM", () => { void Promise.all([handle.close(), remote.close()]) })
process.once("SIGINT", () => { void Promise.all([handle.close(), remote.close()]) })
process.stdin.once("end", () => { void remote.close() })
+22 -8
View File
@@ -1,20 +1,34 @@
import { env } from "../config.js"
import { closePool, pool } from "../db/index.js"
import { applySqlMigrations } from "../db/migrate.js"
import { withSystemDatabaseOperationLock } from "../db/operation-lock.js"
import { assertDatabaseRestoreQuarantineOpen, databaseRestoreQuarantineEnabled } from "../db/database-restore-quarantine.js"
import { ensurePartitionsAround } from "../db/partitions.js"
import { importSqliteToPostgres } from "../db/sqlite-import.js"
import { mcpStateDirectory } from "../modules/mcp/security.js"
import { assertDatabaseMaintenanceStartup } from "../services/database-maintenance-startup.js"
const sqlitePath = process.argv.find((a) => a.startsWith("--sqlite="))?.slice(9) ?? env.DATABASE_PATH
const dryRun = process.argv.includes("--dry-run")
const fullHistory = process.argv.includes("--full-history")
const strict = process.argv.includes("--strict") || !dryRun
await applySqlMigrations(pool)
await ensurePartitionsAround(pool)
const report = await importSqliteToPostgres(pool, sqlitePath, { dryRun, strict, fullHistory })
console.log(JSON.stringify(report, null, 2))
if (!dryRun && report.rejects.length > 0 && strict) {
if (process.env.DATABASE_RUNTIME_REQUEST_FILE !== undefined) {
throw new Error("Импорт SQLite требует отдельного процесса оператора PostgreSQL")
}
const { closePool, pool } = await import("../db/index.js")
try {
const stateDirectory = mcpStateDirectory()
await assertDatabaseMaintenanceStartup(stateDirectory, env.DATABASE_URL)
const report = await withSystemDatabaseOperationLock(() => pool.connect(), async client => {
await assertDatabaseMaintenanceStartup(stateDirectory, env.DATABASE_URL)
if (databaseRestoreQuarantineEnabled()) await assertDatabaseRestoreQuarantineOpen(client)
await applySqlMigrations(pool)
await ensurePartitionsAround(pool)
return importSqliteToPostgres(pool, sqlitePath, { dryRun, strict, fullHistory })
})
console.log(JSON.stringify(report, null, 2))
if (!dryRun && report.rejects.length > 0 && strict) process.exitCode = 1
} finally {
await closePool()
process.exit(1)
}
await closePool()
+18
View File
@@ -0,0 +1,18 @@
import "../config.js"
const args = process.argv.slice(2)
if (args.length > 0 && (args.length !== 1 || args[0] !== "--partitions-only")) {
throw new Error("Допустимый параметр подготовки БД: --partitions-only")
}
if (!process.env.DATABASE_URL || process.env.DATABASE_RUNTIME_REQUEST_FILE !== undefined) {
throw new Error("Подготовка БД требует отдельного процесса оператора с явно заданным DATABASE_URL")
}
const { initDatabase } = await import("../db/bootstrap.js")
const { closePool } = await import("../db/index.js")
try {
await initDatabase(args.length === 1 ? "operator-partitions" : "startup")
} finally {
await closePool()
}
@@ -0,0 +1,25 @@
/** Offline owner command only; credentials and issuer private key never become
* MCP inputs. No schema/key/role creation, native calls or automatic recovery. */
import { resolve } from "node:path"
import { readBandwidthControlFile } from "../services/bandwidth-control-source.js"
import { sealEmptyBandwidthControlSource } from "../services/bandwidth-control-provision.js"
import { BANDWIDTH_ADMISSION_PROPOSAL_DDL } from "../services/bandwidth-admission-schema.js"
import { BANDWIDTH_CONTROL_SOURCE_DDL } from "../services/bandwidth-control-source-schema.js"
const args=process.argv.slice(2)
if(args.length===1&&args[0]==="--print-schema"){
console.log("BEGIN;\nCREATE SCHEMA mmapp_control;\n"+BANDWIDTH_ADMISSION_PROPOSAL_DDL+"\n"+BANDWIDTH_CONTROL_SOURCE_DDL+"\nCOMMIT;")
}else if(args.length!==2||args[0]!=="--config"){
console.error("Использование: npm run bandwidth:control:seal -- --config <абсолютный путь к операторскому JSON>")
process.exitCode=1
}else{
try{
const deadline=Date.now()+5000
const config=JSON.parse((await readBandwidthControlFile(resolve(args[1]),32768,()=>{if(Date.now()>=deadline)throw new Error()})).toString("utf8"))
const record=await sealEmptyBandwidthControlSource(config)
console.log(JSON.stringify({installationId:record.installationId,controlGeneration:record.controlGeneration,sourceSealed:true,applicationSchemaReady:false,nativeDispatchEnabled:false}))
}catch{
console.error("Привязка источника не подтверждена. Проверьте исходный pending-файл и immutable identity; не создавайте новое поколение для обхода отказа.")
process.exitCode=1
}
}
@@ -0,0 +1,14 @@
import { closePool } from "../db/index.js"
import { sealPendingSystemDatabaseRestore } from "../services/system-database-restore-recovery.js"
try {
const [, , operationId, appliedJournalSha256, extra] = process.argv
if (!operationId || !appliedJournalSha256 || extra !== undefined) {
throw new Error("Использование: db:seal-restore-checkpoint <operation-id> <sha256-журнала>")
}
await sealPendingSystemDatabaseRestore(operationId, appliedJournalSha256)
console.log("Контрольная точка PostgreSQL опубликована")
} catch (error) {
console.error(error instanceof Error ? error.message : "Публикация контрольной точки PostgreSQL не подтверждена")
process.exitCode = 1
} finally { await closePool() }
@@ -0,0 +1,13 @@
import { listenForRestoreCheckpointClaims } from "../services/database-restore-checkpoint-claim.js"
try {
const [, , file, socket, extra] = process.argv
if (!file || !socket || extra !== undefined) throw new Error("Использование: db:serve-restore-claims <файл> <локальный-сокет>")
if (process.platform !== "win32") process.umask(0o007)
const server = await listenForRestoreCheckpointClaims(file, socket)
for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => server.close())
console.log("Операторский процесс готов подтверждать одноразовые допуски восстановления PostgreSQL")
} catch {
console.error("Не удалось запустить операторскую службу допуска восстановления PostgreSQL")
process.exitCode = 1
}
@@ -0,0 +1,12 @@
import { closePool } from "../db/index.js"
import { stageSystemDatabaseRestoreCheckpoint } from "../services/system-database-restore-staging.js"
try {
const [, , currentFileSha256, extra] = process.argv
if (!currentFileSha256 || extra !== undefined) throw new Error("Использование: db:stage-restore-checkpoint <sha256-файла-sealed>")
const operationId = await stageSystemDatabaseRestoreCheckpoint(currentFileSha256)
console.log(JSON.stringify({ operationId, status: "pending" }))
} catch (error) {
console.error(error instanceof Error ? error.message : "Допуск PostgreSQL не опубликован")
process.exitCode = 1
} finally { await closePool() }