hivemind: Instructions file for GitHub Copilot

Hivemind Copilot Instructions

This is a TypeScript MCP (Model Context Protocol) server for Obsidian vaults. It provides AI tools with structured access to worldbuilding and knowledge management vaults.

Build, Test, and Lint Commands

# Build
npm run build           # Compile TypeScript to dist/

# Development
npm run dev             # Watch mode - auto-rebuild on changes

# Testing
npm test                # Run full test suite
npm run test:watch      # Run tests in watch mode
npm run test:ui         # Run tests with UI
npm run test:coverage   # Run tests with coverage report

# To run a single test file:
npx vitest run tests/path/to/test.test.ts

# To run tests matching a pattern:
npx vitest run -t "test name pattern"

# Linting
npm run lint            # ESLint check (src/ only, excludes tests/)

# Start server
npm start               # Run the MCP server with config.json

Coverage thresholds (defined in vitest.config.ts):

• Branches: 30%
• Functions: 55%
• Lines: 40%
• Statements: 40%

Architecture Overview

Core Components

MCP Server (src/server.ts, src/index.ts)

• Implements Model Context Protocol for AI tool integration
• Dynamically generates MCP tools based on loaded templates
• Supports both stdio and SSE transport modes
• Main entry point: HivemindServer class

Template System (src/templates/)

• Built-in templates: worldbuilding, research, people-management (in builtin/)
• Community templates: Loaded from community/ directory (planned)
• Template detection: Automatically detects which template a vault uses via detector.ts
• Schema factory: schema-factory.ts creates Zod schemas dynamically from template configs
• Registry: Central registry (registry.ts) holds active template and entity type configs

Templates define:

• Entity types (e.g., character, location, event, faction)
• Fields and validation rules for each type
• Relationships between entity types

Vault Processing (src/vault/)

• reader.ts: Parses Obsidian markdown files with YAML frontmatter
• watcher.ts: Watches vault for file changes using chokidar
• Extracts wikilinks ([[Note Title]]) for relationship building