{"_id":"@ai-craft/brain","name":"@ai-craft/brain","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ai-craft/brain","version":"0.2.0","description":"Per-project MCP stdio server — ask and investigate tools for AI-assisted development","type":"module","main":"./index.js","exports":{".":"./index.js"},"bin":{"brain":"index.js"},"engines":{"node":">=22"},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.0"},"_id":"@ai-craft/brain@0.2.0","_integrity":"sha512-3pTXWLccv05dD1LkpxU/ckOU5fjmfqXNTjrGKh0TBxsF4AcsT8CqdzSk4kRYByUYwmIIeWxRrFMgRihKIiyl+Q==","_resolved":"/private/var/folders/_j/tzygz83s12v4rnxgchnxz55m0000gp/T/e4c5e5e5f521ece5207ca0ecbb801336/ai-craft-brain-0.2.0.tgz","_from":"file:ai-craft-brain-0.2.0.tgz","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-3pTXWLccv05dD1LkpxU/ckOU5fjmfqXNTjrGKh0TBxsF4AcsT8CqdzSk4kRYByUYwmIIeWxRrFMgRihKIiyl+Q==","shasum":"f21e6af01aa54732fcb0e6ce3ffd25c96d1a7d38","tarball":"https://registry.npmjs.org/@ai-craft/brain/-/brain-0.2.0.tgz","fileCount":702,"unpackedSize":4434539,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICjdCaaUfw3/N8lc/dnEkCdb86cXAhhxaZw5csyS6eslAiArfBIRzFpV1TV0B/wkulS3KVeTD8mInSKWXJ6iYI1fwQ=="}]},"_npmUser":{"name":"volkz","email":"delacruzd93@gmail.com"},"directories":{},"maintainers":[{"name":"volkz","email":"delacruzd93@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/brain_0.2.0_1784450392151_0.1875547967613289"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-19T08:39:51.972Z","0.2.0":"2026-07-19T08:39:52.315Z","modified":"2026-07-19T08:39:52.489Z"},"maintainers":[{"name":"volkz","email":"delacruzd93@gmail.com"}],"description":"Per-project MCP stdio server — ask and investigate tools for AI-assisted development","license":"MIT","readme":"# @ai-craft/brain\n\nPer-project MCP stdio server. Exposes project knowledge to Claude Code, Cursor, and other MCP-compatible clients through two tools.\n\n## Tools\n\n| Tool | Mode | Description |\n|------|------|-------------|\n| `ask` | Synchronous, stateless | Returns project context — schema summary + Craftflow memory excerpts — as MCP content for the calling agent to use in its generation. |\n| `investigate` | Async, job-based | Starts a background investigation, returns a job handle. Phase 3 implements results. |\n\n## How it works\n\nThe server uses a three-layer architecture:\n\n1. **Schema acquisition** — `acquireSchema(projectRoot)` scans for `schema.prisma` (preferred) or `migrations/**/*.sql` files, parses them into a `SchemaDict`, and writes the result to `.craftflow/brain/schema-dict.json`. No database credentials required.\n\n2. **Craftflow memory reader** — `readCraftflowMemory(startDir)` walks up the filesystem from the project root to find the nearest `.craftflow/state/project/` directory and reads `activeContext.md` and `patterns.md` as plain text.\n\n3. **Disk cache** — `loadCache` / `saveSchema` / `saveMemory` provide atomic JSON read/write to `.craftflow/brain/` using a tmp-then-rename pattern. The cache directory is gitignored (`**/.craftflow/brain/`) so generated files are never committed.\n\nOn the first `ask` call, the handler warms the cache from schema + Craftflow memory. Subsequent calls serve from the on-disk cache — deserialize only, no re-scan.\n\n## Quick Start\n\n### Claude Code — `.claude/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"brain\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"./node_modules/@ai-craft/brain/index.js\"]\n    }\n  }\n}\n```\n\n### Cursor — `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"brain\": {\n      \"command\": \"node\",\n      \"args\": [\"./node_modules/@ai-craft/brain/index.js\"]\n    }\n  }\n}\n```\n\n### Programmatic (custom transport)\n\n```ts\nimport { createBrainServer } from '@ai-craft/brain';\nimport { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';\n\nconst [, serverTransport] = InMemoryTransport.createLinkedPair();\nawait createBrainServer().connect(serverTransport);\n```\n\n## Requirements\n\nNode >= 22, `@modelcontextprotocol/sdk` >= 1.29.0.\n\n## Known limitations (phase 2)\n\n- **SQL parser — PRIMARY KEY nullable flag:** `PRIMARY KEY` columns declared inline may be incorrectly marked `nullable: true`. Fix planned for phase 3.\n- **Prisma parser — single-line models:** Single-line model definitions (`model Foo {}`) are not parsed correctly. Use multi-line model blocks in real schemas for now.\n- **SQL parser — double-quoted identifiers:** PostgreSQL double-quoted column names (e.g. `\"my column\"`) are silently skipped. Fix planned for phase 3.\n- **`investigate` tool:** Still a stub — returns a \"not yet implemented\" notice. Phase 3 implements async job-based investigations.\n\n## Concept Doc\n\n[`docs/ai/concepts/project-brain-mcp.md`](../../docs/ai/concepts/project-brain-mcp.md) — architecture decisions and full phase roadmap.\n","readmeFilename":"README.md","_rev":"1-4ebeb193c736da4096f2aec61ebe22f1"}