Unified Agent Context System

Unified Agent Context System (MCP)

Globalny serwer Model Context Protocol z rozdzieleniem rdzenia, transportu i modułów narzędzi per domena.

Architektura

• Core (src/core/) — tworzenie instancji McpServer, typy wspólne dla modułów, ToolRegistry ładujący moduły z konfiguracji.
• Transports (src/transports/) — adaptery MCP: Streamable HTTP (http.ts, sesje, Express przez SDK) oraz stdio (stdio.ts) — w src/index.ts domyślnie startuje HTTP; stdio włączasz ręcznie w entry point (krok po kroku: Transport stdio (aktywacja)).
• Observability (src/observability/) — health checks oraz metryki Prometheus; endpointy podpinane w transporcie HTTP (szczegóły: Observability).
• Modules (src/modules/<nazwa>/) — każdy moduł eksportuje register(server, options) i rejestruje narzędzia pod własnym namespace z env / config/modules.config.ts.
• Config (config/modules.config.ts) — lista modułów, flagi ENABLE_MODULE_*, namespace i opcje (np. contentRoot dla portfolio).

Przepływ (obecny domyślny): src/index.ts → createMcpServer() → ToolRegistry.loadModules() → startHttpTransport(buildMcpServer, { port, host }) (Bearer: wymagany niepusty MCP_INTERNAL_TOKEN — http.ts odrzuca start bez niego i weryfikuje nagłówek na każdym żądaniu).

Moduły

Portfolio

Treść z plików Markdown i manifest.json w katalogu content (read-only, ścieżki przez safeJoin z ochroną przed path traversal).

Lib: corpus.ts, paths.ts, frontmatter.ts, search.ts, filterHelpers.ts, toolResponse.ts, validSections.ts, toolManifestData.ts.

Narzędzia (prefix domyślny portfolio_, konfigurowalny przez PORTFOLIO_NAMESPACE):

| Narzędzie | Opis | |-----------|------| | {ns}_get_profile | Profil publiczny | | {ns}_get_about | Sekcja „O mnie” | | {ns}_get_manifest | manifest.json (sekcje, metadane MVP) | | {ns}_search | Wyszukiwanie po korpusie | | {ns}_projects_query, {ns}_projects_list, {ns}_projects_get, {ns}_projects_tags | Projekty | | {ns}_skills_query, {ns}_skills_list, {ns}_skills_get, {ns}_skills_tags, {ns}_skills_categories | Umiejętności | | {ns}_experience_query, {ns}_experience_list, {ns}_experience_get, {ns}_experience_tags | Doświadczenie | | {ns}_courses_query, {ns}_courses_list, {ns}_courses_get, {ns}_courses_tags, {ns}_courses_categories, {ns}_courses_platforms | Kursy |

{ns} = wartość namespace (np. portfolio).

test-tools

Przykładowy moduł demonstracyjny (zod + server.tool): {ns}_get_user_data, {ns}_get_products. Domyślny namespace: test (TEST_TOOLS_NAMESPACE). W środowisku produkcyjnym zwykle wyłączasz: ENABLE_MODULE_TEST_TOOLS=false.

Moduł jest włączony domyślnie (jak portfolio), dopóki nie ustawisz ENABLE_MODULE_*=false.

Struktura repozytorium

.                                 # korzeń repozytorium (nazwa katalogu zależy od klonu)
├── config/
│   └── modules.config.ts          # Moduły, namespace, contentRoot, corpusVersion
├── scripts/
│   └── copy-portfolio-content.mjs # Po tsc: kopiuje content → dist/.../portfolio/content
├── Dockerfile
├── docker-compose.yml             # Przykładowe wdrożenie HTTP (MCP_HOST, MCP_PORT)
├── src/
│   ├── index.ts                   # Entry: server → registry → HTTP (domyślnie)
│   ├── core/
│   │   ├── server.ts
│   │   ├── toolRegistry.ts
│   │   └── types.ts
│   ├── transports/
│   │   ├── http.ts                # Streamable HTTP, /mcp, Bearer; podpina /healthz i /metrics
│   │   └── stdio.ts
│   ├── observability/
│   │   ├── health.ts              # Aggregacja checkHealth włączonych modułów
│   │   ├── metrics.ts             # prom-client: HTTP, sesje, auth, toolsy
│   │   └── instrumentTool.ts      # Wrapper registerTool + observeTool
│   └── modules/
│       ├── portfolio/
│       │   ├── index.ts           # register*: profile, about, manifest, search, projects, skills, experience, courses
│       │   ├── content/           # .md, manifest.json (+ kopia w dist po buildzie)
│       │   ├── lib/
│       │   └── tools/
│       └── test-tools/
│           ├── index.ts
│           └── tools/
└── dist/                          # `tsc` → m.in. dist/src/index.js

Instalacja

npm install

Konfiguracja

cp .env.example .env

Ważne zmienne (szczegóły w .env.example):

• Portfolio: ENABLE_MODULE_PORTFOLIO, PORTFOLIO_NAMESPACE, PORTFOLIO_CONTENT_ROOT, PORTFOLIO_CORPUS_VERSION
• test-tools: ENABLE_MODULE_TEST_TOOLS, TEST_TOOLS_NAMESPACE
• Transport HTTP (aktywny w src/index.ts): MCP_HOST (domyślnie 127.0.0.1), MCP_PORT (domyślnie 3333), MCP_INTERNAL_TOKEN — wymagana niepusta wartość; bez niej proces nie wystartuje; każde żądanie HTTP musi mieć Authorization: Bearer <ten sam token>
• Observability (HTTP): HEALTH_ENABLED / METRICS_ENABLED (domyślnie włączone; wyłączenie: false), HEALTH_PATH (domyślnie /healthz), METRICS_PATH (domyślnie /metrics)

Observability

Warstwa w src/observability/ — health i metryki Prometheus. Endpointy rejestruje wyłącznie transport HTTP w src/transports/http.ts (przy stdio brak /healthz i /metrics). Ścieżki /healthz i /metrics nie wymagają Bearer (middleware auth dotyczy tylko ścieżek pod mount MCP, domyślnie /mcp).

Health (health.ts)

• Włączane, gdy HEALTH_ENABLED !== 'false' (ścieżka: HEALTH_PATH, domyślnie /healthz).
• GET zwraca JSON { status, checks } — HTTP 200 przy status: "ok", 503 przy "degraded".
• buildHealthPayload() przechodzi włączone wpisy z modules.config, dynamicznie ładuje moduł i — jeśli eksportuje opcjonalne checkHealth — zbiera wyniki typu HealthCheck (id, ok, detail? z src/core/types.ts).
• Status globalny: "ok", gdy wszystkie checki mają ok: true; inaczej "degraded". Wyjątek w checkerze staje się checkiem z ok: false.
• Portfolio eksportuje checkHealth: weryfikuje, że contentRoot jest ustawiony i czytelny (portfolio_content_root).

Metryki Prometheus (metrics.ts + instrumentTool.ts)

• Biblioteka: prom-client. Włączane, gdy METRICS_ENABLED !== 'false' (ścieżka: METRICS_PATH, domyślnie /metrics).
• Przy starcie HTTP: initMetrics() — domyślne metryki procesu z prefixem mcp_ oraz gauge mcp_build_info{version="1.0.0"}.
• Endpoint ekspozycji: Content-Type z prom-client, body z register.metrics().

| Metryka | Typ | Etykiety / sens | |---------|-----|-----------------| | mcp_http_requests_total | Counter | method, status_class (1xx…5xx), module | | mcp_auth_failures_total | Counter | reason: missing_token \| invalid_token | | mcp_protocol_errors_total | Counter | module, code (np. missing_module, unknown_module, session_mismatch, invalid_session, …) | | mcp_sessions_active | Gauge | module — aktywne sesje | | mcp_sessions_opened_total / mcp_sessions_closed_total | Counter | module | | mcp_tool_invocations_total | Counter | module, tool, result (ok \| error) | | mcp_tool_duration_seconds | Histogram | module, tool — czas handlera |

Transport HTTP zapisuje m.in. requesty (po res.finish), błędy auth/protokołu oraz lifecycle sesji. Narzędzia portfolio rejestrują się przez registerInstrumentedTool: owija handler, mierzy czas (hrtime) i woła observeTool (sukces / isError / wyjątek).

Request ID

Każde żądanie HTTP dostaje requestId z nagłówka x-request-id (jeśli niepusty) albo świeże randomUUID() — pole na obiekcie requestu w Express.

Uruchomienie

Rozwój (watch)

npm run dev

Produkcja

npm run build
npm start

build uruchamia tsc oraz scripts/copy-portfolio-content.mjs, żeby przy npm start (node dist/src/index.js) katalog content modułu portfolio był dostępny obok skompilowanych plików (domyślny PORTFOLIO_CONTENT_ROOT względem lib w dist).

Transport stdio (aktywacja alternatywy do HTTP)

Alternatywny transport MCP znajduje się w src/transports/stdio.ts: funkcja startStdioTransport(server) podłącza jedną instancję McpServer do StdioServerTransport (komunikacja JSON-RPC MCP wyłącznie przez stdin / stdout). Nadaje się do klientów, które spawnują proces Node i nie otwierają portu HTTP (typowo Cursor z konfiguracją command + args).

Jak włączyć stdio (ręczna zmiana w src/index.ts, potem npm run build):

1. Import: odkomentuj import { startStdioTransport } from './transports/stdio.js'; i zakomentuj (lub usuń) import startHttpTransport, jeśli nie jest już potrzebny.
2. Funkcja main(): usuń lub zakomentuj cały obecny blok: sonda startowa (probe z createServerWithModules + probe.close()), a także startHttpTransport(...). Sonda zamyka pierwszą instancję serwera — przed stdio nie powinna zostawiać zamkniętego serwera jako jedynej ścieżki.
3. Zastąp logiką w stylu poniżej — jedna instancja serwera na proces, bez nasłuchu TCP:

const { server, loadedModules } = await createServerWithModules();
console.error(`[Server] Loaded ${loadedModules.length} modules: ${loadedModules.join(', ')}`);
await startStdioTransport(server);

1. W repozytorium w komentarzu jest skrócona wersja tej samej idei (linia przy // Stdio (jeden proces, jedna sesja):); możesz ją wkleić zamiast ręcznego składania bloku — byle nie mieszać jednocześnie z startHttpTransport w tym samym main().

Zmienne MCP_HOST / MCP_PORT / MCP_INTERNAL_TOKEN nie dotyczą trybu stdio (brak serwera HTTP). Po przełączeniu z powrotem na HTTP przywróć import i wywołanie startHttpTransport oraz (opcjonalnie) sondę diagnostyczną, jeśli z niej korzystasz.

Integracja z Cursor IDE

Uwaga: domyślny src/index.ts uruchamia serwer HTTP, a nie MCP po stdio. Konfiguracja Cursor z polami command + args zakłada zwykle stdio. Żeby ta ścieżka działała, najpierw aktywuj stdio według sekcji Transport stdio (aktywacja alternatywy do HTTP) (albo wydziel osobny plik startowy tylko pod stdio, żeby nie przełączać index.ts przy każdej zmianie środowiska).

Gdy masz już tryb stdio w procesie uruchamianym przez Cursor:

1. Zbuduj projekt: npm run build
2. W konfiguracji MCP ustaw serwer uruchamiany przez Node ze ścieżką do skompilowanego entry point (ten sam plik co dziś, ale po przełączeniu na stdio w kodzie):

{
  "mcpServers": {
    "unified_agent_context_mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\matej\\Desktop\\projekt JS\\custom_mcp_server\\dist\\src\\index.js"
      ],
      "env": {
        "ENABLE_MODULE_PORTFOLIO": "true",
        "ENABLE_MODULE_TEST_TOOLS": "true",
        "PORTFOLIO_NAMESPACE": "portfolio",
        "PORTFOLIO_CONTENT_ROOT": "C:\\Users\\matej\\Desktop\\projekt JS\\custom_mcp_server\\dist\\src\\modules\\portfolio\\content"
      }
    }
  }
}

Klucz unified_agent_context_mcp w JSON jest dowolny (to etykieta w Cursorze); możesz trzymać np. mateo2314_mcp_server, jeśli masz już starą konfigurację.

Dostosuj ścieżki do swojego dysku. Dla samego portfolio możesz wskazać src\\...\\content przy tsx/dev; przy npm start wygodniej jest katalog w dist po skrypcie kopiującym.

1. Zrestartuj Cursor i sprawdź panel MCP.

HTTP (VPS / agenci zdalni): po npm start endpoint MCP jest pod ścieżką /mcp (Streamable HTTP). Ustaw MCP_INTERNAL_TOKEN w środowisku (np. .env / docker-compose) i dołącz do każdego żądania nagłówek Authorization: Bearer … z tą wartością. W repozytorium jest przykład portów i MCP_HOST=0.0.0.0 w docker-compose.yml.

Testowanie w Cursor

Jakie narzędzia MCP są dostępne?

Użyj portfolio_get_profile i pokaż wynik

Wyszukaj "TypeScript" przez portfolio_search

Treść portfolio

Pliki w src/modules/portfolio/content/ (po buildzie także pod dist/.../content/). Struktura zależy od Twojego korpusu; obowiązuje m.in. manifest.json zgodny z narzędziem get_manifest.

Przykład front matter w .md:

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

Opis...

Migracja / rozszerzenia

Baza zamiast plików

Zachowaj nazwy narzędzi i kontrakty; podmień implementację w warstwie lib (np. corpus.ts) na odczyt z DB. Zmienne typu PORTFOLIO_DB_URL są przygotowane w .env.example jako szkic.

Transport HTTP

Zaimplementowany w src/transports/http.ts (Streamable HTTP, sesje, wymagany Bearer MCP_INTERNAL_TOKEN). Szerszy opis planu / decyzji mógł być w MCP.md — plik może być wyłączony z gita (patrz .gitignore); stan faktyczny zawsze w kodzie index.ts + http.ts.

Transport stdio

Implementacja: src/transports/stdio.ts. Aktywacja w entry point: Transport stdio (aktywacja alternatywy do HTTP).

Dodawanie modułu

1. Katalog src/modules/<nazwa>/ z index.ts i export async function register(server, options).
2. Wpis w config/modules.config.ts (nazwa = segment ścieżki importu ../modules/${name}/index.js).
3. Zmienne ENABLE_MODULE_<NAZWA> / namespace w .env według konwencji projektu.

Dokumentacja

• MCP_MVP.md — plan MVP
• MCP.md — architektura globalnego serwera i transporty
• Model Context Protocol

Troubleshooting

Brak połączenia z klientem MCP

• Logi: Output → MCP
• Ścieżki w Windows: poprawne escapowanie \\ w JSON
• Czy istnieje dist/src/index.js po npm run build
• Cursor + command/args: czy proces naprawdę używa stdio? Domyślny index.js startuje HTTP — wtedy Cursor nie „zobaczy” MCP po stdin/stdout; przełącz transport w kodzie albo osobny entry pod stdio

Brak narzędzi / pusty moduł

• W logach powinna być linia w stylu: Loaded N modules: portfolio, test-tools
• ENABLE_MODULE_PORTFOLIO=false wyłącza portfolio; to samo dla test-tools
• Portfolio: czy content istnieje (src lub dist + skrypt kopiujący)

Path traversal detected

Zamierzone dla ścieżek wychodzących poza PORTFOLIO_CONTENT_ROOT. Sprawdź PORTFOLIO_CONTENT_ROOT i argumenty narzędzi.

Licencja

ISC