83 lines
2.0 KiB
Markdown
83 lines
2.0 KiB
Markdown
# Development Guide
|
|
|
|
## Project Layout
|
|
|
|
```text
|
|
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
|
|
|
|
1. Add a method to `CortexTools`.
|
|
2. Add or update a service method in `CortexMemoryService`.
|
|
3. Use `[McpServerTool]` with a stable `Name`.
|
|
4. Set `UseStructuredContent = true` when the tool returns structured data.
|
|
5. Add an integration test.
|
|
6. Update `docs/mcp-tools.md`.
|
|
|
|
## Adding a Database Change
|
|
|
|
1. Update domain/entity configuration.
|
|
2. Add an EF Core migration.
|
|
3. Make sure pgvector-specific SQL remains explicit when needed.
|
|
4. Run:
|
|
|
|
```powershell
|
|
.\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.
|