Skip to main content

Project Structure

Detailed breakdown of MCP Gatekeeper's monorepo structure.

Root Structure​

mcp-gatekeeper/
├── apps/                    # Application workspaces
│   ├── backend/            # FastAPI Python backend
│   ├── frontend/           # React TypeScript frontend
│   └── docs/               # Docusaurus documentation
├── memory/                 # Project architecture documentation
├── tests/                  # Test files
├── package.json            # Root workspace config
├── turbo.json             # Turborepo configuration
└── README.md              # Project README

Backend Structure​

apps/backend/
├── app/
│   ├── api/               # API route handlers
│   │   ├── agents.py
│   │   ├── http_servers.py
│   │   ├── agent_http_servers.py
│   │   ├── logs.py
│   │   ├── metrics.py
│   │   ├── packages.py
│   │   ├── servers.py
│   │   └── websocket.py
│   ├── core/              # Core functionality
│   │   ├── config.py      # Settings
│   │   ├── database.py    # Database setup
│   │   ├── middleware.py  # Authentication middleware
│   │   └── constants.py   # Constants
│   ├── models/            # SQLAlchemy models
│   │   ├── server.py
│   │   ├── metric.py
│   │   ├── log.py
│   │   └── http_server.py
│   ├── schemas/           # Pydantic schemas
│   │   └── requests.py
│   ├── services/          # Business logic
│   │   ├── agent_config_scanner.py
│   │   ├── http_proxy.py
│   │   ├── mcp_client.py
│   │   └── package_manager.py
│   ├── utils/             # Utility functions
│   └── main.py            # FastAPI app entry
├── venv/                  # Python virtual environment
├── requirements.txt       # Python dependencies
├── mcpgatekeeper.db      # SQLite database
└── package.json          # Node scripts

Key Backend Files​

  • main.py: FastAPI application initialization, CORS, routes
  • http_proxy.py: Transparent HTTP proxy for MCP servers
  • mcp_client.py: JSON-RPC client for STDIO MCP servers
  • package_manager.py: npm package installation and management
  • agent_config_scanner.py: Agent configuration file management

Frontend Structure​

apps/frontend/
├── src/
│   ├── components/        # Reusable components
│   │   ├── Layout.tsx
│   │   ├── ErrorBoundary.tsx
│   │   ├── FilterBar.tsx
│   │   ├── TerminalViewer.tsx
│   │   ├── ServerCard.tsx
│   │   └── ...
│   ├── pages/            # Page components
│   │   ├── Dashboard.tsx
│   │   ├── Servers.tsx
│   │   ├── Packages.tsx
│   │   ├── HttpServers.tsx
│   │   ├── Agents.tsx
│   │   ├── Metrics.tsx
│   │   ├── Logs.tsx
│   │   ├── ServerDetail.tsx
│   │   └── ServerActivity.tsx
│   ├── services/         # API client
│   │   └── api.ts
│   ├── theme/            # MUI theme
│   │   └── theme.ts
│   ├── App.tsx           # Root component
│   ├── main.tsx          # Entry point
│   └── index.css         # Global styles
├── public/               # Static assets
├── index.html           # HTML template
├── vite.config.ts       # Vite configuration
├── tsconfig.json        # TypeScript config
└── package.json         # Dependencies

Key Frontend Files​

  • api.ts: Centralized Axios client with auth
  • theme.ts: Light/dark theme definitions
  • Layout.tsx: Sidebar navigation wrapper
  • Dashboard.tsx: Main dashboard page

Documentation Structure​

apps/docs/
├── docs/                 # Documentation pages
│   ├── getting-started/
│   ├── features/
│   ├── architecture/
│   ├── api-reference/
│   └── development/
├── src/                  # Custom components
│   └── pages/
│       └── index.tsx     # Landing page
├── static/              # Static assets
├── docusaurus.config.ts # Docusaurus config
└── sidebars.ts         # Sidebar navigation

Memory Directory​

memory/
├── 01-project-overview.md
├── 02-monorepo-structure.md
├── 03-backend-architecture.md
├── 04-frontend-architecture.md
├── 19-http-mcp-transport.md
└── ...                   # Architecture docs

Purpose: Single source of truth for project architecture and implementation details.

Configuration Files​

Root Level​

  • package.json: Workspace configuration, scripts
  • turbo.json: Turborepo task orchestration

Backend​

  • requirements.txt: Python dependencies
  • .env: Environment variables (not in repo)

Frontend​

  • vite.config.ts: Build tool configuration
  • tsconfig.json: TypeScript compiler options

Data Storage​

  • Database: apps/backend/mcpgatekeeper.db (SQLite)
  • Packages: ~/.mcp-gatekeeper/packages/ (npm packages)
  • Agent Configs: Platform-specific locations

For detailed architecture, see Architecture Overview.