| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 13 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 1 | 8 | 0% |
What each file covers
Sections
0 shared · 6 only in A · 13 only in B- − @second-brain/mcp-server — Agent Instructions
- − Entry Point
- − Transports
- − Tools (32 total)
- − Resources
- − Adding a New MCP Tool
- + Second Brain — Windsurf Rules
- + Project Overview
- + Tech Stack
- + Monorepo
- + Commands
- + Coding Rules
- + Always
- + Never
- + Backend Patterns
- + Frontend Patterns
- + Testing
- + Data Model
- + Documentation
Commands
neither file has anySection tags
0 shared · 1 only in A · 8 only in B- − agent-behaviour
- + setup
- + test
- + code-style
- + architecture
- + types
- + monorepo
- + do-not
- + docs
Line diff
thangaram611/second-brain · packages/mcp-server/AGENTS.md
@@ −1 @@
1# @second-brain/mcp-server — Agent Instructions
2
3MCP (Model Context Protocol) server exposing 32 tools for knowledge graph operations.
4
5## Entry Point
6
7`src/server.ts` → `createMcpServer()` registers all tools and resources.
8
9## Transports
10
11- `src/stdio.ts` — stdio transport (for CLI-based MCP clients)
12- `src/http.ts` — Streamable HTTP transport
13- `src/transports/` — Transport helpers
14
15## Tools (32 total)
16
17| File | Category | Count |
18|------|----------|-------|
19| `src/tools/read-tools.ts` | Read operations | 15 |
20| `src/tools/write-tools.ts` | Write operations | 12 |
21| `src/tools/pipeline-tools.ts` | Pipeline operations | 5 |
22| `src/tools/formatters.ts` | Response formatting helpers | — |
23
24## Resources
25
26`src/resources/` — MCP resource definitions (graph metadata, schemas).
27
28## Adding a New MCP Tool
29
301. Add tool definition in the appropriate file under `src/tools/`
312. Register in `src/server.ts` via `createMcpServer()`
323. Follow existing patterns: Zod schema for input, formatter for output
33
thangaram611/second-brain · .windsurfrules
@@ +1 @@
1# Second Brain — Windsurf Rules
2
3## Project Overview
4
5Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
6
7For full architecture: see docs/architecture.md
8For agent instructions: see AGENTS.md
9
10## Tech Stack
11
12- Runtime: Node.js 22+, ESM only ("type": "module")
13- Language: TypeScript 5.8+ strict mode
14- Database: SQLite (better-sqlite3) + Drizzle ORM, WAL mode
15- Search: FTS5 (BM25) + sqlite-vec (cosine KNN), Reciprocal Rank Fusion
16- Validation: Zod v4
17- Testing: Vitest, in-memory SQLite
18- Build: tsdown (ESM), tsc (type-check)
19- Frontend: React 19, Zustand, Cytoscape.js, Tailwind CSS, Radix UI
20- Sync: Yjs CRDTs via Hocuspocus relay
21- IDs: ULIDs (ulidx). Never UUID
22- Timestamps: ISO 8601 strings. Never unix timestamps
23
24## Monorepo
25
26packages/types — Shared TypeScript types
27packages/core — Knowledge graph engine (Brain class in src/brain.ts)
28packages/collectors — Data collectors + streaming providers
29packages/ingestion — LLM extraction + embedding pipeline
30packages/sync — Yjs CRDT sync bridge
31packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
32apps/server — Express 5 REST API + WebSocket (port 7430)
33apps/ui — React 19 + Cytoscape.js (port 5173)
34apps/relay — Hocuspocus CRDT relay (port 7421)
35tools/cli — brain CLI (Commander.js)
36
37## Commands
38
39pnpm install, pnpm build, pnpm test, pnpm check-types, pnpm dev
40
41## Coding Rules
42
43### Always
44- ESM only. Named exports. Re-export from index.ts
45- Use workspace imports: @second-brain/core, @second-brain/types
46- Zod schemas for all external input validation
47- ULIDs for IDs (via ulidx)
48- ISO 8601 for timestamps
49- Namespace field on all entities/relations
50- In-memory SQLite for tests
51- Try-catch with descriptive errors
52- batchUpsert for bulk operations
53
54### Never
55- Use `any` type
56- Use path aliases
57- Use UUIDs
58- Use unix timestamps or Date objects in storage
59- Write to entities_fts directly (auto-maintained via triggers)
60- Mutate stored confidence (decay is read-side only)
61- Sync 'personal' namespace
62- Import from package internals (use public API)
63
64## Backend Patterns
65
66- Drizzle ORM for queries (schema in packages/core/src/schema/)
67- Brain class is main facade (packages/core/src/brain.ts)
68- Relations: unique constraint on (sourceId, targetId, type)
69- Use createOrGet for idempotent relations
70- WebSocket broadcast after mutations
71- MCP tools: packages/mcp-server/src/tools/
72
73## Frontend Patterns
74
75- React 19 functional components
76- Zustand stores (one per feature in apps/ui/src/store/)
77- Cytoscape.js with diff-based rendering
78- Tailwind dark theme (zinc-950 bg)
79- REST client: apps/ui/src/lib/api.ts
80- WebSocket: apps/ui/src/lib/ws.ts (auto-reconnect)
81- HashRouter (React Router 7)
82
83## Testing
84
85- Vitest with globals (no imports for describe/it/expect)
86- In-memory SQLite for all DB tests
87- Co-located: __tests__/*.test.ts
88- Use Brain class directly (not HTTP)
89- Test happy path + error cases
90
91## Data Model
92
93Entity types (15): concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, implementation, pull_request, merge_request, branch
94
95Relation types (20): relates_to, depends_on, implements, supersedes, contradicts, derived_from, authored_by, decided_in, uses, tests, contains, co_changes_with, preceded_by, blocks, reviewed_by, merged_in_mr, merged_in_pr, touches_file, owns, parallel_with
96
97## Documentation
98
99- docs/architecture.md — Full technical architecture
100- docs/getting-started.md — Usage guide
101- docs/api-reference.md — REST API + MCP + CLI reference
102- AGENTS.md — Detailed agent instructions
103
@@ −1 +1 @@
1−# @second-brain/mcp-server — Agent Instructions
1+# Second Brain — Windsurf Rules
22
3−MCP (Model Context Protocol) server exposing 32 tools for knowledge graph operations.
3+## Project Overview
44
5−## Entry Point
5+Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
66
7−`src/server.ts` → `createMcpServer()` registers all tools and resources.
7+For full architecture: see docs/architecture.md
8+For agent instructions: see AGENTS.md
89
9−## Transports
10+## Tech Stack
1011
11−- `src/stdio.ts` — stdio transport (for CLI-based MCP clients)
12−- `src/http.ts` — Streamable HTTP transport
13−- `src/transports/` — Transport helpers
12+- Runtime: Node.js 22+, ESM only ("type": "module")
13+- Language: TypeScript 5.8+ strict mode
14+- Database: SQLite (better-sqlite3) + Drizzle ORM, WAL mode
15+- Search: FTS5 (BM25) + sqlite-vec (cosine KNN), Reciprocal Rank Fusion
16+- Validation: Zod v4
17+- Testing: Vitest, in-memory SQLite
18+- Build: tsdown (ESM), tsc (type-check)
19+- Frontend: React 19, Zustand, Cytoscape.js, Tailwind CSS, Radix UI
20+- Sync: Yjs CRDTs via Hocuspocus relay
21+- IDs: ULIDs (ulidx). Never UUID
22+- Timestamps: ISO 8601 strings. Never unix timestamps
1423
15−## Tools (32 total)
24+## Monorepo
1625
17−| File | Category | Count |
18−|------|----------|-------|
19−| `src/tools/read-tools.ts` | Read operations | 15 |
20−| `src/tools/write-tools.ts` | Write operations | 12 |
21−| `src/tools/pipeline-tools.ts` | Pipeline operations | 5 |
22−| `src/tools/formatters.ts` | Response formatting helpers | — |
26+packages/types — Shared TypeScript types
27+packages/core — Knowledge graph engine (Brain class in src/brain.ts)
28+packages/collectors — Data collectors + streaming providers
29+packages/ingestion — LLM extraction + embedding pipeline
30+packages/sync — Yjs CRDT sync bridge
31+packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
32+apps/server — Express 5 REST API + WebSocket (port 7430)
33+apps/ui — React 19 + Cytoscape.js (port 5173)
34+apps/relay — Hocuspocus CRDT relay (port 7421)
35+tools/cli — brain CLI (Commander.js)
2336
24−## Resources
37+## Commands
2538
26−`src/resources/` — MCP resource definitions (graph metadata, schemas).
39+pnpm install, pnpm build, pnpm test, pnpm check-types, pnpm dev
2740
28−## Adding a New MCP Tool
41+## Coding Rules
2942
30−1. Add tool definition in the appropriate file under `src/tools/`
31−2. Register in `src/server.ts` via `createMcpServer()`
32−3. Follow existing patterns: Zod schema for input, formatter for output
43+### Always
44+- ESM only. Named exports. Re-export from index.ts
45+- Use workspace imports: @second-brain/core, @second-brain/types
46+- Zod schemas for all external input validation
47+- ULIDs for IDs (via ulidx)
48+- ISO 8601 for timestamps
49+- Namespace field on all entities/relations
50+- In-memory SQLite for tests
51+- Try-catch with descriptive errors
52+- batchUpsert for bulk operations
53+
54+### Never
55+- Use `any` type
56+- Use path aliases
57+- Use UUIDs
58+- Use unix timestamps or Date objects in storage
59+- Write to entities_fts directly (auto-maintained via triggers)
60+- Mutate stored confidence (decay is read-side only)
61+- Sync 'personal' namespace
62+- Import from package internals (use public API)
63+
64+## Backend Patterns
65+
66+- Drizzle ORM for queries (schema in packages/core/src/schema/)
67+- Brain class is main facade (packages/core/src/brain.ts)
68+- Relations: unique constraint on (sourceId, targetId, type)
69+- Use createOrGet for idempotent relations
70+- WebSocket broadcast after mutations
71+- MCP tools: packages/mcp-server/src/tools/
72+
73+## Frontend Patterns
74+
75+- React 19 functional components
76+- Zustand stores (one per feature in apps/ui/src/store/)
77+- Cytoscape.js with diff-based rendering
78+- Tailwind dark theme (zinc-950 bg)
79+- REST client: apps/ui/src/lib/api.ts
80+- WebSocket: apps/ui/src/lib/ws.ts (auto-reconnect)
81+- HashRouter (React Router 7)
82+
83+## Testing
84+
85+- Vitest with globals (no imports for describe/it/expect)
86+- In-memory SQLite for all DB tests
87+- Co-located: __tests__/*.test.ts
88+- Use Brain class directly (not HTTP)
89+- Test happy path + error cases
90+
91+## Data Model
92+
93+Entity types (15): concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, implementation, pull_request, merge_request, branch
94+
95+Relation types (20): relates_to, depends_on, implements, supersedes, contradicts, derived_from, authored_by, decided_in, uses, tests, contains, co_changes_with, preceded_by, blocks, reviewed_by, merged_in_mr, merged_in_pr, touches_file, owns, parallel_with
96+
97+## Documentation
98+
99+- docs/architecture.md — Full technical architecture
100+- docs/getting-started.md — Usage guide
101+- docs/api-reference.md — REST API + MCP + CLI reference
102+- AGENTS.md — Detailed agent instructions
33103
