This guide provides the technical foundation for contributing to Vault Cortex. It covers the local development environment, testing philosophy, structured logging architecture, and the comprehensive security toolchain that maintains the project's high security posture.
Vault Cortex requires Node.js >= 24 as specified in .nvmrc1 It is recommended to use nvm to manage versions. The project uses strict engine checks and exact dependency versions to ensure environment parity .npmrc1-3
VAULT_PATH and MCP_AUTH_TOKEN to point to a local Obsidian vault for testing CONTRIBUTING.md35-36The project supports three primary development workflows CONTRIBUTING.md26-59:
| Mode | Command | Description |
|---|---|---|
| MCP Server | npm run dev:mcp | Direct execution with hot reload via tsx. Fastest feedback loop for logic changes. |
| Docker (Local) | npm run dev:docker | Builds from source using the local target in the Dockerfile. Validates container behavior. |
| MCP Inspector | npx @modelcontextprotocol/inspector | Interactive UI to test tool invocations against a running server. |
The cli/ directory contains a standalone npm package CONTRIBUTING.md61-68 While it shares some devDependencies with the root, it has its own tsconfig.json. When modifying templates in deploy/, you must run npm run sync:cli-env-blocks to update the environment blocks in cli/src/env.ts derived from deploy/*/.env.example CONTRIBUTING.md74-78
Vault Cortex uses Vitest for its test suite, configured in vitest.config.ts3-13 The project emphasizes behavioral testing over implementation details, following a "spec" naming convention where each it() block describes a specific system behavior CONTRIBUTING.md103-109
For details, see Testing.
The project follows Conventional Commits to automate versioning and uses GitHub Actions for automated building, scanning, and deployment. Releases are cut by the maintainer via manual dispatch or tag pushes CONTRIBUTING.md160-175
For details, see CI/CD and Release Process.
The logging system in src/logger.ts is designed for high observability, producing structured JSON logs src/logger.ts8-14
The system uses a "chain" pattern via the child() method src/logger.ts25 It supports lazy-resolved properties, allowing context that isn't yet available at child creation (like an MCP sessionId) to be captured at emit time src/logger.ts127-140
logger.child to bind sessionId and clientIp src/vault-mcp/mcp-core/mcp-router.ts107-112info, warn, and error levels, the logger captures the file and line number using a V8 stack trace helper getCallerSource() src/logger.ts42-59vault-mcp-YYYY-MM-DD.log) with configurable retention src/logger.ts63-104Vault Cortex maintains a "Defense in Depth" posture through a multi-layered security toolchain SECURITY.md25-31
resolveSafePath() to block path traversal SECURITY.md34-35 and atomicWriteFileExclusive() to prevent TOCTOU races SECURITY.md46-49This diagram bridges the developer's local actions to the automated entities in the GitHub Actions environment.
This diagram maps the flow of a request through the system to the specific code entities responsible for observability.
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.