Development Guide

Project Layout

src/
  Cortex.Api/
    Contracts/
    Data/
    Domain/
    Migrations/
    Options/
    Services/
    Tools/
  Cortex.Web/
    Components/
    wwwroot/
tests/
  Cortex.IntegrationTests/
scripts/
docs/

Important Files

File	Purpose
`src/Cortex.Api/Program.cs`	App startup, DI, MCP route, migration/seed modes.
`src/Cortex.Api/Tools/CortexTools.cs`	MCP tool surface.
`src/Cortex.Api/Services/CortexMemoryService.cs`	Project/item/search behavior.
`src/Cortex.Api/Data/CortexDbContext.cs`	EF Core model.
`src/Cortex.Web/Components/Pages/Home.razor`	Optional Blazor web UI dashboard.
`src/Cortex.Api/Migrations`	Database schema migrations.
`docker-compose.yml`	Dev stack.
`docker-compose.test.yml`	Test stack.

Adding a Tool

Add a method to CortexTools.
Add or update a service method in CortexMemoryService.
Use [McpServerTool] with a stable Name.
Set UseStructuredContent = true when the tool returns structured data.
Add an integration test.
Update docs/mcp-tools.md.

Adding a Database Change

Update domain/entity configuration.
Add an EF Core migration.
Make sure pgvector-specific SQL remains explicit when needed.
Run:
```
.\scripts\test-integration.ps1
```

Changing the Embedding Model

The current model produces 384-dimensional vectors. If the new model has a different dimension, update:

Cortex:EmbeddingDimensions
migration/schema for vector(N)
indexes
docs

Changing dimensions for existing data requires either a re-embedding migration or a new embedding table/column strategy.

Local Docker Config

The scripts keep Docker CLI config inside the workspace where practical:

.docker

This folder is ignored by Git. NuGet uses the normal machine/user configuration.

Coding Notes

Keep projects explicit.
Keep tool names stable.
Prefer structured tool output.
Keep Docker ops scriptable.
Add tests for MCP behavior, not just internal service behavior.

2.0 KiB Raw Blame History