Hein (Warky)
1ceb317f4b
Some checks failed
CI / build-and-test (push) Failing after -29m56s
- Added language_tags, library_tags, framework_tags, and domain_tags to agent skills. - Introduced new commands: get_skill and get_guardrail for fetching specific skills and guardrails. - Updated database schema and migration scripts to accommodate new fields. - Enhanced skill listing functionality to support filtering by new tags. - Improved error handling and response structures for skill-related operations.
102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
## What This Project Is
|
|
|
|
AMCS (Avalon Memory Control Service) is an MCP server written in Go that provides memory, knowledge, and task management for AI agents. It exposes 56+ tools via HTTP/SSE MCP transport and includes a Svelte 5 admin UI embedded in the binary.
|
|
|
|
# Agent Rules
|
|
|
|
Keep your answers short. Question everything, never assume or guess. Ask the user if you are unsure about anything.
|
|
You must use the AMCS MCP system tools. Set Origin as the active project and always capture summaries of what was done as thoughts using the capture_thought tool. If amcs is not available write files to doc/llm/log/yyyymmdd_hh.md
|
|
When working on postgresql use the postgresql skill. On go/api/backend the go-skill and for the frontend the "svelte-architect" skill.
|
|
|
|
## Commands
|
|
|
|
### Build & Run
|
|
```bash
|
|
make build # Build server binary (outputs to bin/amcs-server), embeds UI
|
|
make build-cli # Build CLI binary (bin/amcs-cli)
|
|
make clean # Remove bin/
|
|
|
|
# Run locally (builds UI then starts server)
|
|
./scripts/run-local.sh configs/dev.yaml
|
|
|
|
# UI hot-reload dev server (proxy to backend on :8080)
|
|
make ui-dev # http://localhost:5173
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
make test # All tests (svelte-check + go test ./...)
|
|
go test ./internal/tools -run TestFunctionName -v # Single test
|
|
go test ./internal/tools -v # Package tests
|
|
```
|
|
|
|
### Database
|
|
```bash
|
|
make migrate # Apply SQL migrations
|
|
make check-schema-drift # Verify no drift between DBML and SQL
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Key Pattern: Store → Tool → MCP Handler
|
|
|
|
Every tool domain follows the same three-layer pattern:
|
|
|
|
1. **Store** (`internal/store/`) — database access via BUN ORM + pgx. One file per domain (e.g., `thoughts.go`, `plans.go`).
|
|
2. **Tool** (`internal/tools/`) — MCP tool handler structs with a `Handle(ctx, req, input)` method. Input/output types are plain Go structs; JSON schemas are auto-generated from struct tags.
|
|
3. **Registration** (`internal/mcpserver/handlers.go`) — each domain has a `registerXxxTools(server, logger, ts)` function called from `NewHandlers`.
|
|
|
|
### Adding a New Tool Domain
|
|
|
|
Follow the checklist in `internal/tools/` (see `project_conventions.md` in memory, or look at any existing domain like `skills.go` as a reference):
|
|
- Define input/output structs with `jsonschema` tags
|
|
- Implement a struct with `Handle` method
|
|
- Add the struct to `ToolSet` in `mcpserver/handlers.go`
|
|
- Wire the store in `internal/store/db.go`
|
|
- Add a `registerXxxTools` call in `NewHandlers`
|
|
|
|
### AI Provider Architecture
|
|
|
|
Configured in YAML under `ai.providers`. Each role (embeddings, metadata extraction) supports a primary provider and a fallback chain. Providers are named references (litellm, ollama, openrouter) that resolve to OpenAI-compatible endpoints. Health tracking per provider with cooldown on transient failures.
|
|
|
|
### Error Handling
|
|
|
|
All tool errors return structured `mcperrors.RPCError` with:
|
|
- `data.type` — machine-readable category (`invalid_input`, `project_required`, `entity_not_found`, etc.)
|
|
- `data.field` / `data.detail` / `data.hint` — structured validation data
|
|
|
|
Use helpers in `internal/mcperrors/` rather than raw errors.
|
|
|
|
### Authentication
|
|
|
|
- API key via `x-brain-key` header (dev/simple deployments)
|
|
- OAuth 2.0 client credentials for production
|
|
- Session store tracks active project per client connection
|
|
|
|
### Database Schema
|
|
|
|
DBML files in `schema/` are the source of truth for the database schema. Never edit the generated SQL or Go models directly — always edit the DBML, then regenerate:
|
|
|
|
```bash
|
|
make generate-migrations # DBML → SQL migration files
|
|
make generate-models # DBML → Go model structs
|
|
make migrate # Apply pending migrations to the database
|
|
```
|
|
|
|
All primary keys are `bigserial int64` (migrated from UUID in migration 015).
|
|
|
|
### Frontend
|
|
|
|
Svelte 5 + Tailwind + Skeleton UI in `ui/`. Built via pnpm and embedded into the Go binary as a static filesystem. The Vite dev server proxies API calls to the backend on `:8080`.
|
|
|
|
The UI uses **resolvespec-js** for admin CRUD views. The backend API for the UI follows the **ResolveSpec** convention — resource endpoints, filtering, and pagination are structured according to that spec.
|
|
|
|
## Configuration
|
|
|
|
YAML config with schema `version: 2`. Key env var overrides:
|
|
- `DATABASE_URL` — PostgreSQL connection string
|
|
- `AMCS_LITELLM_API_KEY`, `AMCS_OPENROUTER_API_KEY` — AI provider keys
|
|
- `AMCS_SERVER_PORT` — defaults to 8080
|
|
|
|
See `configs/config.example.yaml` for the full schema. Config auto-migrates v1→v2 on startup.
|