Unified Agent Context System (MCP)

Unified Agent Context System to dedykowana warstwa kontekstowa oparta o Model Context Protocol. Łączy portfolio, notatki, narzędzia diagnostyczne i obserwowalność w jeden serwer MCP, który może zasilać agentów AI uporządkowanymi danymi z kilku domen.

Spis Treści

• Możliwości

• Rola Narzędzia

• Środowiska

• Architektura

• Transporty

• Moduły i narzędzia

• Konfiguracja

• Obsługa Operacyjna

• Observability

• Docker

• Integracja z klientami MCP

• Treść portfolio

• Dodawanie modułu

• Licencja

Related MCP server: mcpdeployment

Możliwości

Rola Narzędzia

System pełni rolę dedykowanej warstwy kontekstowej dla agentów AI, ale pozostaje zorganizowany jak pełnoprawny serwer produkcyjny: ma moduły, izolację transportu, metryki, health checks i jawne kontrakty narzędzi. Zamiast trzymać kontekst w jednym dużym promptcie, wystawia go jako zestaw narzędzi MCP z czytelnymi namespace'ami.

Najważniejsze scenariusze:

• prezentowanie danych portfolio przez narzędzia portfolio_*,

• wyszukiwanie i filtrowanie treści z lokalnego korpusu Markdown,

• pobieranie i zapisywanie notatek Trilium przez trilium_*,

• wystawienie modułów przez HTTP dla agentów lub środowisk zdalnych,

• monitorowanie działania przez /healthz i /metrics.

Adres modułu w transporcie HTTP ma postać:

http://127.0.0.1:3333/mcp/<moduleId>

Przykłady: /mcp/portfolio, /mcp/trilium, /mcp/test-tools.

Środowiska

Serwer jest projektowany jako jedna warstwa MCP działająca w dwóch kontekstach operacyjnych:

Moduł trilium jest rozwijany na branchu feat/trilium-integration.

Architektura

flowchart LR
    Entry["src/index.ts"] --> Config["config/modules.config.ts"]
    Entry --> HTTP["startHttpTransport()"]
    HTTP --> Route["/mcp/:moduleId"]
    Route --> Registry["ToolRegistry"]
    Registry --> Portfolio["portfolio module"]
    Registry --> Trilium["trilium module"]
    Registry --> TestTools["test-tools module"]
    Portfolio --> PortfolioTools["portfolio_* tools"]
    Trilium --> TriliumTools["trilium_* tools"]
    TestTools --> TestToolsTools["test_* tools"]
    HTTP --> Health["/healthz"]
    HTTP --> Metrics["/metrics"]

Główne warstwy:

Przepływ Sesji HTTP

sequenceDiagram
    participant Client as MCP client
    participant HTTP as HTTP transport
    participant Config as modules.config
    participant Registry as ToolRegistry
    participant Module as Module tools

    Client->>HTTP: POST /mcp/:moduleId initialize
    HTTP->>Config: getEnabledModuleByName(moduleId)
    Config-->>HTTP: ModuleConfig
    HTTP->>Registry: build McpServer for module
    Registry->>Module: register(server, options)
    HTTP-->>Client: mcp-session-id
    Client->>HTTP: POST/GET/DELETE with mcp-session-id
    HTTP->>Module: handle MCP request

W HTTP moduleId pochodzi ze ścieżki URL, np. /mcp/portfolio. Namespace narzędzi jest osobną wartością konfiguracyjną, np. PORTFOLIO_NAMESPACE=portfolio, i wpływa na nazwy narzędzi typu portfolio_get_profile.

Transporty

HTTP

HTTP startuje z src/index.ts przez startHttpTransport(buildMcpServerForModule, { port, host }).

Wymagania:

• MCP_INTERNAL_TOKEN musi być ustawiony i niepusty.

• Każde żądanie do /mcp/<moduleId> musi mieć nagłówek Authorization: Bearer <token>.

• /healthz i /metrics nie wymagają Bearer tokena.

Domyślne wartości:

stdio

startStdioTransport(server) istnieje w src/transports/stdio.ts, ale nie jest podłączony w domyślnym src/index.ts. Żeby użyć stdio, trzeba przygotować osobny entry point albo ręcznie przełączyć index.ts z HTTP na stdio.

Minimalny schemat:

const server = createMcpServer();
const registry = new ToolRegistry(server);
await registry.loadSingleModule(moduleConfig);
await startStdioTransport(server);

Moduły i narzędzia

flowchart TD
    Modules["src/modules"]

    Modules --> Portfolio["portfolio"]
    Portfolio --> P1["profile / about / manifest"]
    P1 --> P2["search"]
    P2 --> P3["projects / skills / experience / courses"]

    Modules --> Trilium["trilium"]
    Trilium --> T1["get_note"]
    T1 --> T2["list_by_label"]
    T2 --> T3["get_tree"]
    T3 --> T4["save_note"]

    Modules --> TestTools["test-tools"]
    TestTools --> D1["get_user_data"]
    D1 --> D2["get_products"]

    Portfolio ~~~ Trilium
    Trilium ~~~ TestTools

Portfolio

Moduł portfolio obsługuje środowisko produkcyjne: udostępnia publiczne dane portfolio z plików Markdown i manifest.json. Treść jest czytana z PORTFOLIO_CONTENT_ROOT, a ścieżki są chronione przed path traversal.

Domyślny namespace narzędzi: portfolio.

Trilium

Moduł trilium obsługuje środowisko homelab: integruje MCP z Trilium Notes przez ETAPI. Wymaga TRILIUM_BASE_URL i TRILIUM_API_TOKEN. Kod modułu znajduje się na branchu feat/trilium-integration.

Domyślny namespace narzędzi: trilium.

Ważne: chronione notatki Trilium są obsługiwane jako błąd narzędzia bez ujawniania treści.

test-tools

Moduł kontrolny do sprawdzania działania rejestracji narzędzi i odpowiedzi MCP.

Domyślny namespace narzędzi: test.

W konfiguracji publicznej lub produkcyjnej zwykle warto go wyłączyć:

ENABLE_MODULE_TEST_TOOLS=false

Konfiguracja

Konfiguracja modułów znajduje się w config/modules.config.ts, a przykładowe zmienne w .env.example.

Zmienne Wspólne

Portfolio

Trilium

Jeśli Trilium jest włączony bez TRILIUM_BASE_URL i TRILIUM_API_TOKEN, src/index.ts przerwie start procesu.

test-tools

Obsługa Operacyjna

Build uruchamia tsc oraz scripts/copy-portfolio-content.mjs, żeby content portfolio był dostępny po kompilacji.

Observability

Endpointy observability są rejestrowane tylko przez transport HTTP.

Health

GET /healthz zwraca:

{
  "status": "ok",
  "checks": []
}

Status globalny:

• ok - wszystkie checki włączonych modułów są poprawne.

• degraded - co najmniej jeden check zwrócił błąd.

Aktualne checki:

Metryki Prometheus

GET /metrics zwraca metryki z prom-client.

Każde żądanie HTTP dostaje requestId z nagłówka x-request-id albo z randomUUID().

Docker

Projekt zawiera Dockerfile i docker-compose.yml.

docker compose up --build

W docker-compose.yml kontener wystawia port 8090, dlatego w .env dla tego wariantu ustaw:

MCP_HOST=0.0.0.0
MCP_PORT=8090
MCP_INTERNAL_TOKEN=production-token

Przykładowy endpoint po starcie:

http://127.0.0.1:8090/mcp/portfolio

Integracja z klientami MCP

HTTP

Dla klientów obsługujących Streamable HTTP użyj adresu modułu:

http://<host>:<port>/mcp/<moduleId>

Do żądań MCP dodaj nagłówek:

Authorization: Bearer <MCP_INTERNAL_TOKEN>

Cursor i stdio

Domyślny entry point uruchamia HTTP, nie stdio. Jeśli klient wymaga konfiguracji command + args, przygotuj wariant stdio, który wywołuje startStdioTransport(server).

Po zbudowaniu projektu typowa ścieżka entry pointu to:

dist/src/index.js

Treść portfolio

Pliki portfolio znajdują się w:

src/modules/portfolio/content/

Po buildzie content jest kopiowany do:

dist/src/modules/portfolio/content/

Przykładowy front matter:

---
project_name: Mój projekt
project_category: Web Development
tech_stack: Next.js, TypeScript
---

Opis projektu...

Dodawanie modułu

1. Utwórz katalog src/modules/<nazwa>/.

2. Dodaj index.ts z eksportem register(server, options).

3. Opcjonalnie dodaj checkHealth(config).

4. Dodaj wpis do config/modules.config.ts.

5. Ustal ENABLE_MODULE_<NAZWA> i namespace w .env.example.

6. Rejestruj narzędzia z nazwą opartą o namespace, np. ${namespace}_my_tool.

HTTP używa name z konfiguracji jako moduleId w ścieżce /mcp/<moduleId>. Namespace służy do nazw narzędzi i może być inny niż moduleId.

Licencja

ISC