AI助手工具整合平台

graph TD
    subgraph "Admin Operations"
        Admin[Admin UI/API] --> Commands[CQRS Commands]
        Commands --> Sources[UpstreamSource]
        Commands --> Tools[SourceTool]
    end

    subgraph "Event Store - Write Model"
        Sources --> KurrentDB[(KurrentDB)]
        Tools --> KurrentDB
    end

    subgraph "Projections - Read Model"
        KurrentDB --> Projector[Event Projector]
        Projector --> MongoDB[(MongoDB)]
        Projector --> Redis[(Redis Cache)]
    end

    subgraph "Agent Runtime"
        Agent((AI Agent)) --> API[REST API]
        API --> Queries[CQRS Queries]
        Queries --> MongoDB
        Agent --> Executor[Tool Executor]
        Executor --> Keycloak{Keycloak}
        Keycloak --> Upstream[Upstream Services]
    end

POST /api/sources
{
  "name": "cml-mcp",
  "url": "file:///app/plugins/cml-mcp",
  "source_type": "mcp",
  "mcp_plugin_dir": "/app/plugins/cml-mcp",
  "mcp_transport_type": "stdio",
  "mcp_lifecycle_mode": "transient",
  "mcp_runtime_hint": "uvx",
  "mcp_env_vars": {
    "CML_URL": "${secrets:cml-url}",
    "CML_TOKEN": "${secrets:cml-token}"
  }
}

tools-provider/                          # Repository root
├── src/
│   ├── tools-provider/                  # Main MCP Tools Provider service
│   │   ├── main.py                      # FastAPI app factory with Neuroglia DI
│   │   ├── api/                         # REST API layer
│   │   │   ├── controllers/             # Sources, Tools, Groups, Policies, Agent
│   │   │   ├── dependencies.py          # Auth dependencies (session + JWT)
│   │   │   └── services/                # DualAuthService, OpenAPI config
│   │   ├── application/                 # CQRS handlers
│   │   │   ├── commands/                # Write operations (Create*, Update*, Delete*)
│   │   │   ├── queries/                 # Read operations (Get*, Search)
│   │   │   ├── events/                  # Domain & integration event handlers
│   │   │   └── services/                # ToolExecutor, OpenAPISourceAdapter
│   │   ├── domain/                      # Pure domain model
│   │   │   ├── entities/                # Aggregates: Source, Tool, Group, Policy, Label
│   │   │   ├── events/                  # Domain events with @cloudevent decorator
│   │   │   └── repositories/            # Repository interfaces (ports)
│   │   ├── integration/                 # Concrete implementations
│   │   │   ├── models/                  # DTOs with @queryable decorator
│   │   │   └── repositories/            # Motor (MongoDB) repositories
│   │   ├── infrastructure/              # External adapters (Redis, Keycloak)
│   │   ├── ui/                          # Admin UI (Bootstrap 5 + Parcel)
│   │   └── tests/                       # Pytest suites (domain, application)
│   ├── agent-host/                      # Chat interface BFF service
│   │   ├── main.py                      # FastAPI app with ReActAgent
│   │   ├── api/controllers/             # Chat, Auth, Settings endpoints
│   │   ├── application/                 # Commands, Queries, ChatService
│   │   ├── domain/entities/             # Conversation aggregate
│   │   └── ui/                          # Chat UI (Bootstrap 5 + Parcel)
│   └── upstream-sample/                 # Sample Pizzeria OpenAPI service
│       └── app/                         # FastAPI demo backend
├── docs/                                # MkDocs documentation
├── deployment/                          # Keycloak realm, OTEL collector config
├── docker-compose.yml                   # Full local stack
└── Makefile                             # Root orchestration commands

# Complete setup for new developers
make setup

# Start infrastructure (KurrentDB, MongoDB, Keycloak, Redis)
make up

# Run the application locally
make run

# See all available commands
make help

# Build and start all services
make up

# View logs
make logs

# Stop services
make down

# Admin-only endpoints use require_roles dependency
@delete("/{source_id}")
async def delete_source(self, user: dict = Depends(require_roles("admin"))):
    ...

# Application
APP_HOST=127.0.0.1
APP_PORT=8040

# Keycloak OAuth2/OIDC
KEYCLOAK_URL=http://localhost:8041
KEYCLOAK_REALM=tools-provider
KEYCLOAK_CLIENT_ID=tools-provider-public

# Database connections (JSON)
CONNECTION_STRINGS='{"eventstore": "esdb://...", "mongo": "mongodb://..."}'

# Redis
REDIS_ENABLED=true
REDIS_URL=redis://redis:6379/0

# OpenTelemetry
OTEL_ENABLED=true
OTEL_ENDPOINT=http://otel-collector:4317

make up          # Start all services in background
make down        # Stop and remove services
make logs        # Show logs from all services
make rebuild     # Rebuild from scratch (no cache)

make setup       # Complete setup (Python + Node deps, build UI)
make run         # Run application locally with hot-reload
make run-debug   # Run with LOG_LEVEL=DEBUG

make test        # Run all tests
make test-cov    # Run tests with coverage report
make lint        # Run linting checks (Ruff)
make format      # Format code with Black

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=. --cov-report=html

# Run specific test categories
make test-domain       # Domain layer tests
make test-application  # CQRS handler tests

poetry run pre-commit install --install-hooks
poetry run pre-commit run --all-files

docker build -t tools-provider:latest .
docker run -p 8040:8040 tools-provider:latest