Codegraph / MCP for AI Agents

Developer tooling for AI-assisted navigation of MyHoreca Pay. Not a production runtime dependency.

Purpose

Codegraph helps AI agents:

• inspect project structure and module boundaries;
• find symbol usages and API contract touchpoints;
• avoid duplicate DTOs, services, and UI components;
• validate architecture dependency rules;
• keep architecture documentation aligned with code.

Two layers

1. Repository manifest (always available)

Path: codegraph/manifest.yaml

Machine-readable index of:

Area	What is indexed
Backend	C# projects, allowed/forbidden references, key interfaces
Frontend	API layer, shared components, pages, routes, tests
API surface	endpoint → controller → hook → page → docs → tests
Docs	portal paths and AI agent docs
Rules	architecture tests and boundary notes

Agents should read codegraph/manifest.yaml before creating new services, DTOs, components, or endpoints.

2. Optional MCP server (local IDE tooling)

An MCP codegraph server indexes the repo into a queryable graph (symbols, imports, callers, impact). Examples of compatible local tools:

• codegraph-ai — tree-sitter + MCP (search, get_context, project_overview)
• CodeGraph — local SQLite graph via MCP
• cgh — multi-language graph + docs FTS

Copy .cursor/mcp.json.example (repository root) to .cursor/mcp.json and adjust for your chosen server. Do not commit personal MCP secrets or machine-specific paths unless the team standardizes them.

C# note: many codegraph MCP tools index TypeScript/JavaScript best. For .NET boundaries, combine MCP with codegraph/manifest.yaml and dotnet test on MyHoreca.Pay.ArchitectureTests.

Agent workflow (mandatory)

Before backend architecture changes

1. Read codegraph/manifest.yaml → modules.backend
2. Run or review architecture tests: backend/tests/MyHoreca.Pay.ArchitectureTests
3. If MCP is enabled: query impact/callers for affected symbols
4. Do not add references that violate allowed_references / forbidden_references

Before creating a service / interface / DTO

1. Search manifest shared_symbols.backend_interfaces and api_surface
2. Grep backend: IBankAdapter, IPaymentAllocationService, similar names
3. Extend existing abstractions in Application or Domain — do not duplicate

Before creating a UI component

1. Check shared_symbols.frontend_components in manifest
2. Inspect frontend/src/shared/ui/index.ts
3. Extend shared components; pages stay thin

Before changing API contracts

For each endpoint, update all touchpoints listed in manifest api_surface:

• backend controller/handler
• frontend/src/api/contracts/apiContracts.ts
• frontend/src/api/hooks/usePayApi.ts
• consuming pages
• tests (unit/integration/Playwright)
• docs/docs/backend/api.md

After structure changes

Update in the same PR:

• codegraph/manifest.yaml
• docs/docs/backend/api.md (if API changed)
• docs/docs/architecture/* (if boundaries changed)
• AGENTS.md / .cursor/rules/codegraph.mdc (if agent rules changed)

What codegraph understands

Kind	Source
C# projects & references	*.csproj, manifest, architecture tests
TypeScript imports	MCP index or grep/frontend/src
React components/hooks	manifest + frontend/src/components, frontend/src/api/hooks
API contracts	manifest api_surface, apiContracts.ts, controllers
Docs references	docs/docs/**, vitepress config
Tests	manifest links + backend/tests, frontend/tests, docs/playwright

Dependency validation

Automated (CI/local):

cd backend
dotnet test tests/MyHoreca.Pay.ArchitectureTests

Documented rules in manifest dependency_rules:

• Domain must not reference Infrastructure/Persistence/Api
• Application must not reference Api
• Bank parsing stays in BankStatements adapters
• Syrve writes stay behind ISyrvePaymentPostingAppService approval gate

MCP tool usage (when configured)

Prefer graph queries over blind file reads:

Task	MCP (if available)	Fallback without MCP
Find symbol	search / symbol_lookup	grep + manifest
Who calls X	find_callers / codegraph_callers	grep references
API impact	manifest api_surface + grep /api/	manifest + grep
Module boundaries	manifest modules.backend	read *.csproj
UI reuse	manifest shared_symbols.frontend_components	read frontend/src/shared/ui

Rule: use codegraph/MCP for navigation and impact analysis; use direct file edits for implementation.

Related files

• AGENTS.md (repository root)
• .cursor/rules/codegraph.mdc (repository root)
• .cursor/mcp.json.example (repository root)
• docs/docs/ai-agents/rules.md

Non-goals

• Codegraph is not deployed with API/Gateway/Frontend containers
• Codegraph MCP is not required for local dev or CI build
• Do not add codegraph packages to Directory.Packages.props or frontend package.json runtime deps