MCP servery — API špecifikácia

1. Klient (web app, mobile, AI agent) presmeruje na auth.activity.sportup.sk
2. Užívateľ sa prihlási, schváli scopes (napr. "Activity.app chce: activity.read activity.write")
3. auth.activity.sportup.sk vráti authorization code
4. Klient vymení code za access token + refresh token
5. Access token použije v hlavičke: Authorization: Bearer eyJ...

Request príde →
  1. JWT validácia (signature, expiry, audience)
  2. Tenant scoping: request.tenantId = token.tnt
  3. Scope check: má token požadovaný scope?
  4. ACL check: má person konkrétne práva na konkrétny resource?
  5. Audit log (pre citlivé operácie)
  6. Spustenie business logiky cez servisnú vrstvu

register_person(input: {
  firstName: string,
  lastName: string,
  birthDate: string, // ISO date
  nationality: string, // ISO 3166-1 alpha-2
  email?: string,
  phone?: string,
  identifierNational?: string, // šifrované cez CSFLE
  language: 'sk' | 'cs' | 'en' | ...,
  primaryRole: 'athlete' | 'professional' | 'fan' | 'supporter',
}): Person
// Scope: registry.write
// ACL: admin tenanta
// Errors: PERSON_DUPLICATE_EMAIL, PERSON_DUPLICATE_IDENTIFIER
 
update_person(personId: string, patch: Partial<Person>): Person
// Scope: registry.write
// ACL: admin tenanta alebo samotná osoba (self-update niektorých polí)
// Errors: PERSON_NOT_FOUND, PERSON_DUPLICATE_EMAIL
 
deactivate_person(personId: string, reason: string): { success: boolean }
// Scope: registry.write
// ACL: admin tenanta
// Effect: sets deletedAt, anonymizes some PII per GDPR
 
lookup_person_by_identifier(input: {
  identifierType: 'email' | 'national_id' | 'phone',
  value: string,
}): Person | null
// Scope: registry.read (pre national_id vyžaduje registry.admin)
// ACL: tenant scope
// Use case: vyhľadávanie pri registrácii noveho člena

create_organization(input: {
  type: 'club' | 'federation' | 'commission' | 'educational' | 'sponsor',
  legalName: string,
  displayName: string,
  ico?: string,
  parentOrgId?: string,
  defaultRetentionDays?: number,
  minorSelfJoinAge?: number,
}): Organization
// Scope: registry.admin
// ACL: system admin
 
update_organization(orgId: string, patch: Partial<Organization>): Organization
// Scope: registry.write
// ACL: admin tej organizácie
 
add_member(input: {
  organizationId: string,
  personId: string,
  role: 'athlete' | 'coach' | 'referee' | ...,
  startedAt?: string,
}): OrganizationMember
// Scope: registry.write
// ACL: admin organizácie
 
end_membership(memberId: string, endedAt: string, reason?: string): OrganizationMember
// Scope: registry.write
// ACL: admin organizácie
 
add_organization_domain(input: {
  organizationId: string,
  hostname: string,
  isPrimary: boolean,
}): OrganizationDomain
// Scope: registry.write
// ACL: admin organizácie
// Effect: vygeneruje verifyToken, vráti DNS instrukcie
 
verify_organization_domain(domainId: string): OrganizationDomain
// Scope: registry.write
// ACL: admin organizácie
// Effect: kontrola TXT recordu, ak passes → status='active', triggers TLS issuance

issue_license(input: {
  personId: string,
  licenseType: string,
  level: string,
  issuingOrgId: string,
  validUntil: string,
  creditsRequired?: number,
}): License
// Scope: registry.write
// ACL: admin issuingOrgId organizácie
 
renew_license(licenseId: string, newValidUntil: string): License
// Scope: registry.write
// ACL: admin issuing org
 
suspend_license(licenseId: string, reason: string): License
// Scope: registry.write
// ACL: admin issuing org
 
revoke_license(licenseId: string, reason: string): License
// Scope: registry.write
// ACL: admin issuing org
 
add_license_credits(licenseId: string, credits: number, source: string): License
// Scope: registry.write
// ACL: admin issuing org alebo ďalšie autorizované organizácie (vzdelávacie inštitúcie)

list_codelists(): Codelist[]
// Scope: registry.read
 
add_codelist_value(input: {
  codelist: string,
  code: string,
  ordering: number,
  translations: Record<Locale, { label: string, description?: string }>,
  parentValueId?: string,
}): CodelistValue
// Scope: registry.admin (pre globálne) alebo registry.write s isCustomizable=true (pre org-custom)
 
update_codelist_translation(input: {
  codelistValueId: string,
  language: string,
  label: string,
  description?: string,
}): CodelistValue
// Scope: registry.admin pre globálne, registry.write pre org-custom
// Pre crowdsourced preklady: vyžaduje subsequent verify cez registry.admin

import { Client } from '@modelcontextprotocol/sdk/client';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse';
 
const client = new Client({ name: 'activity.sportup.sk', version: '1.0.0' }, {
  capabilities: { resources: {}, tools: {} },
});
 
await client.connect(new SSEClientTransport(
  new URL('https://registry-mcp.activity.sportup.sk/mcp'),
  { headers: { Authorization: `Bearer ${accessToken}` } }
));
 
// Read resource
const person = await client.readResource({
  uri: `registry://persons/${personId}`,
});
 
// Call tool
const result = await client.callTool({
  name: 'register_person',
  arguments: {
    firstName: 'Tomáš',
    lastName: 'Vilček',
    birthDate: '1995-03-12',
    nationality: 'SK',
    email: 'tomas@example.sk',
    language: 'sk',
    primaryRole: 'professional',
  },
});

log_training(input: {
  personId: string,
  occurredAt: string,
  durationMinutes: number,
  trainingType: 'conditioning' | 'technical' | 'tactical' | 'recovery',
  intensity?: number, // 1-10 RPE
  location?: string,
  notes?: string,
}): Training
// Scope: activity.write
// ACL: vlastník (osoba) alebo tréner s aktívnou rolou
 
log_match(input: {
  personId: string,
  matchId: string,
  role: string, // "main_referee", "assistant", "player_starter", ...
  result?: object, // sport-specific
}): MatchParticipation
// Scope: activity.write
// ACL: vlastník alebo delegát zápasu
 
log_medical_treatment(input: {
  personId: string,
  occurredAt: string,
  diagnosis?: string,
  treatment: string,
  recordedByPersonId: string, // musí mať medical/physiotherapist license
}): MedicalTreatment
// Scope: activity.write
// ACL: medical personnel s aktívnou licenciou
// Audit: append-only log
 
log_donation(input: {
  donorPersonId?: string,
  donorOrganizationId?: string,
  recipientType: 'person' | 'organization' | 'event',
  recipientId: string,
  amount: number,
  currency: string,
  purpose?: string,
}): Donation
// Scope: activity.write
// ACL: donor musí byť autentifikovaný

create_mentoring_cycle(input: {
  mentorPersonId: string,
  menteePersonId: string,
  sportId: string,
  level: 'regional' | 'national' | 'uefa' | 'fifa',
  startedAt?: string,
}): MentoringCycle
// Scope: activity.write
// ACL: musí volať sám mentor (foundedByPersonId == mentorPersonId)
// Validation: mentee má hotové základné vzdelávanie pre danú úroveň
 
add_external_mentor(cycleId: string, externalPersonId: string): MentoringCycle
// Scope: activity.write
// ACL: mentor cyklu
 
pause_mentoring_cycle(cycleId: string, reason: string): MentoringCycle
// Scope: activity.write
// ACL: mentor alebo mentee cyklu
 
resume_mentoring_cycle(cycleId: string): MentoringCycle
// Scope: activity.write
// ACL: mentor cyklu
 
complete_mentoring_cycle(input: {
  cycleId: string,
  finalEvaluation: string, // min 1 znak; bez tohto neprejde do completed
}): MentoringCycle
// Scope: activity.write
// ACL: mentor cyklu (jediný)
 
terminate_mentoring_cycle(cycleId: string, reason: string): MentoringCycle
// Scope: activity.write
// ACL: mentor alebo mentee cyklu
 
propose_mentoring_session(input: {
  cycleId: string,
  occurredAt: string,
  durationMinutes: number,
  format: 'in_person' | 'online' | 'phone' | 'written' | 'hybrid',
  location?: string,
  onlinePlatform?: string,
  topicProposal: string, // mentee popíše, čo chce riešiť
}): MentoringSession
// Scope: activity.write
// ACL: mentor alebo mentee cyklu
// Status: 'proposed'
 
record_mentoring_session(input: {
  sessionId?: string, // ak existuje proposed session, doplňame; ak nie, vytvoríme nový
  cycleId: string,
  occurredAt: string,
  durationMinutes: number,
  format: ...,
  location?: string,
  onlinePlatform?: string,
  topics: string[], // 1-3 z mentoring_session_topic
  matchReferenceId?: string,
  summary: string, // min 50 znakov
  outcome: string, // min 30 znakov
  nextSteps?: string,
  competencyTags?: string[],
  attachments?: Attachment[],
  externalLinks?: ExternalLink[],
  linkedConvId?: string,
  rangeStartMsgId?: string,
  rangeEndMsgId?: string,
}): MentoringSession
// Scope: activity.write
// ACL: mentor cyklu (jediný)
// Status: 'recorded'
// Effect: notifikácia mentee + audit log
 
reject_mentoring_session(sessionId: string, reason: string): MentoringSession
// Scope: activity.write
// ACL: mentor cyklu
// Status: 'proposed' → 'rejected'
 
cancel_mentoring_session(sessionId: string, reason: string): MentoringSession
// Scope: activity.write
// ACL: mentor cyklu, do 24h od recordedAt
// Status: 'recorded' → 'cancelled'
 
update_mentoring_session(sessionId: string, patch: Partial<MentoringSession>): MentoringSession
// Scope: activity.write
// ACL: mentor cyklu, do 24h od recordedAt
// Effect: editovaná značka, audit log, notifikácia mentee
 
set_session_private_note(sessionId: string, body: string): void
// Scope: activity.write
// ACL: mentor cyklu (jediný môže zapisovať)
 
get_session_private_note(sessionId: string): { body: string }
// Scope: activity.read
// ACL: mentor cyklu + admin organizácie (audit-only, log access)
// Effect: každé čítanie audit log

add_activity_comment(input: {
  activityType: string,
  activityId: string,
  body: string,
  parentCommentId?: string,
}): ActivityComment
// Scope: activity.write
// ACL: per activityType, viď acl/matrix-comments.md
 
edit_activity_comment(commentId: string, body: string): ActivityComment
// Scope: activity.write
// ACL: autor (vlastný komentár)
 
delete_activity_comment(commentId: string, reason?: string): { success: boolean }
// Scope: activity.write (vlastné) alebo activity.moderate (cudzie)
// ACL: autor alebo moderátor
 
list_activity_comments(input: {
  activityType: string,
  activityId: string,
  cursor?: string,
  limit?: number,
}): { comments: ActivityComment[], nextCursor?: string }
// Scope: activity.read
// ACL: per activityType

// Internal event (publikované na Redis Pub/Sub)
{
  type: 'mentoring_session.recorded' | 'mentoring_session.updated' | 'mentoring_session.cancelled',
  tenantId: string,
  sessionId: string,
  cycleId: string,
  notifyPersonIds: [menteePersonId], // a prípadne externí mentori, predseda komisie
  timestamp: string,
}

create_conversation(input: {
  kind: 'direct' | 'group' | 'broadcast',
  participantIds: string[], // osoby; pre direct musí byť presne 2
  proxyForMinors?: Array<{ parentPersonId: string, minorPersonId: string }>,
  title?: string, // povinné pre group
  owningOrgId: string,
}): Conversation
// Scope: courier.write
// ACL: defaultné pravidlá (kto smie iniciovať, viď acl/matrix-courier.md)
// Validation: pre direct sa overí, že obaja majú aktívny vzťah (mentor-mentee, tréner-zverenec, atď.)
 
add_participant(input: {
  conversationId: string,
  personId: string,
  representedMinorId?: string,
  participantType: 'direct' | 'proxy_for_minor' | 'staff' | 'observer',
  role: 'member' | 'admin' | 'publisher' | 'subscriber',
}): ConversationParticipant
// Scope: courier.write
// ACL: admin konverzácie
// Validation: pre proxy_for_minor sa overí ParentalAccess
 
remove_participant(conversationId: string, participantId: string, reason?: string): void
// Scope: courier.write
// ACL: admin konverzácie alebo samotný účastník (leave)
 
leave_conversation(conversationId: string): void
// Scope: courier.write
// ACL: účastník konverzácie
 
archive_conversation(conversationId: string): Conversation
// Scope: courier.admin
// ACL: admin konverzácie
 
mute_conversation(conversationId: string, dndActive: boolean): ConversationParticipant
// Scope: courier.write
// ACL: účastník
// Validation: kind != 'direct' (DND nie pre 1:1)
 
set_conversation_retention(conversationId: string, retentionDays: number): Conversation
// Scope: courier.admin
// ACL: admin organizácie konverzácie

send_message(input: {
  conversationId: string,
  body: string, // ciphertext pre direct (E2E)
  representedMinorId?: string, // ak posiela proxy rodič
  replyToMessageId?: string,
  attachments?: Attachment[],
  externalLinks?: ExternalLink[],
}): Message
// Scope: courier.write
// ACL: účastník s 'member' alebo 'publisher' rolou
// Effect: publikuje na Redis Pub/Sub kanál pre real-time delivery
 
edit_message(messageId: string, newBody: string): Message
// Scope: courier.write
// ACL: autor správy
// Window: do napr. 24h od poslania (parametrizovateľné)
 
delete_message(messageId: string): { success: boolean }
// Scope: courier.write (vlastné) alebo courier.admin (cudzie ako moderátor)
// ACL: autor alebo admin organizácie
// Effect: soft-delete; pre direct E2E sa odstráni ciphertext (klienti majú lokálnu kópiu)
 
mark_as_read(input: {
  conversationId: string,
  upToMessageId: string,
}): void
// Scope: courier.write
// ACL: účastník
 
react_to_message(input: {
  messageId: string,
  reaction: string, // emoji shortname, e.g. ":thumbsup:"
}): void
// Scope: courier.write
// ACL: účastník

report_message(messageId: string, reason: string): { reportId: string }
// Scope: courier.write
// ACL: účastník
// Effect: queue pre admin organizácie; nemodifikuje správu
 
block_person(personId: string): void
// Scope: courier.write
// ACL: self (vždy povolené)
// Effect: skryje správy danej osoby pre volajúceho
 
unblock_person(personId: string): void
// Scope: courier.write
// ACL: self

link_message_range_to_activity(input: {
  conversationId: string,
  startMessageId: string,
  endMessageId: string,
  activityType: string,
  activityId: string,
}): void
// Scope: courier.write + activity.write
// ACL: účastník konverzácie + autor aktivity
// Effect: aktivita získa odkaz na rozsah správ, viditeľný v UI ako embed
// Use case: "Vytvoriť mentoring sedenie z týchto správ"

GET /sse/conversations/{conversationId}
Authorization: Bearer ...
Accept: text/event-stream

event: message.created
data: {"messageId": "...", "authorPersonId": "...", "createdAt": "..."}

event: message.edited
data: {"messageId": "...", "editedAt": "..."}

event: message.deleted
data: {"messageId": "..."}

event: participant.added
data: {"participantId": "...", "personId": "..."}

event: typing.started
data: {"personId": "..."}

{
  "jsonrpc": "2.0",
  "id": "...",
  "error": {
    "code": -32000,
    "message": "Person not found",
    "data": {
      "errorCode": "PERSON_NOT_FOUND",
      "personId": "abc123",
      "traceId": "trace-xyz"
    }
  }
}

// Request
{
  limit: 50,           // max 100
  cursor?: string,     // opaque, vrátený z predchádzajúceho volania
}
 
// Response
{
  items: [...],
  nextCursor?: string, // null ak nie je ďalšia stránka
}

Fastify (HTTP server)
  + @modelcontextprotocol/sdk (MCP server implementácia)
  + Fastify SSE plugin (server-sent events)
  + Fastify JWT plugin (auth)
  + Native MongoDB driver
  + Zod (validácia)
  + Pino (structured logging)
  + OpenTelemetry SDK

registry-mcp/
├── src/
│   ├── index.ts                  # bootstrap
│   ├── server.ts                 # Fastify + MCP setup
│   ├── auth/                     # JWT validation, scope check
│   ├── tenancy/                  # tenant scoping middleware
│   ├── resources/                # MCP resource handlers
│   │   ├── persons.ts
│   │   ├── organizations.ts
│   │   └── ...
│   ├── tools/                    # MCP tool handlers
│   │   ├── personTools.ts
│   │   ├── organizationTools.ts
│   │   └── ...
│   ├── services/                 # business logika, cross-collection invariants
│   │   ├── PersonService.ts
│   │   └── ...
│   ├── repositories/             # MongoDB queries
│   │   ├── PersonRepository.ts
│   │   └── ...
│   └── shared/                   # zdielané typy, errors, audit
├── schemas/                      # Zod schémy (zdielané s frontendom cez monorepo)
├── migrations/                   # MongoDB migrácie
└── tests/

// packages/schemas/src/person.ts
import { z } from 'zod';
export const PersonInputSchema = z.object({
  firstName: z.string().min(1).max(100),
  lastName: z.string().min(1).max(100),
  // ...
});
export type PersonInput = z.infer<typeof PersonInputSchema>;

// services/registry-mcp uses it for tool input validation
// apps/activity.sportup.sk uses it in React Hook Form