# Enterprise MCP Server

> A modular, security-focused Model Context Protocol (MCP) server that exposes enterprise-ready tools, prompts, and resources through a unified MCP interface.

---

## 📌 Project Overview

The **Enterprise MCP Server** is a Python-based MCP server built with **FastMCP**.

It provides a single interface for interacting with:

- 📁 Filesystem operations
- 🗄️ Database operations
- 🌐 REST APIs
- 🖥️ System utilities
- 🤖 AI generation
- 💬 Reusable MCP prompts
- 📚 MCP resources

The project follows a layered architecture with dedicated **tools, services, validation, permission management, configuration, logging, and persistence** components.

The implementation also includes database audit logging, SQL safety validation, explicit database execution permissions, authentication/authorization controls, and automated testing.

---

## 🚀 Project Status

**Status: ✅ Implementation Complete**

| Area | Status |
|---|---|
| MCP Server | ✅ Complete |
| Tool Registry | ✅ Complete |
| Filesystem Tools | ✅ 5 tools |
| Database Tools | ✅ 3 tools |
| REST API | ✅ 1 tool |
| System Utilities | ✅ 4 tools |
| AI Integration | ✅ 1 tool |
| MCP Prompts | ✅ 3 prompts |
| MCP Resources | ✅ 3 resources |
| Database Persistence | ✅ Complete |
| Audit Logging | ✅ Complete |
| SQL Safety Validation | ✅ Complete |
| Database Permission Policy | ✅ Complete |
| Authentication / Authorization | ✅ Complete |
| Automated Tests | ✅ **101 passed** |
| MCP Inspector Verification | ✅ Complete |

---

## ✨ Key Features

### MCP Capabilities

- FastMCP-based server
- Idempotent server initialization
- Centralized tool registry
- 14 registered MCP tools
- 3 reusable MCP prompts
- 3 MCP resources

### Security

- Authentication and authorization layer
- Read/write database separation
- Database execute permission control
- SQL query validation
- Multiple-statement rejection
- Destructive SQL pattern rejection
- Filesystem workspace restrictions
- Environment-based secret management
- Audit logging

### Engineering

- Layered architecture
- Centralized configuration
- Structured application logging
- Service-layer separation
- Pydantic request/response models
- SQLAlchemy database integration
- Automated unit and persistence tests
- MCP Inspector validation

---

# 🏗️ Architecture

```text
                         ┌──────────────────────┐
                         │     MCP Client       │
                         │   / MCP Inspector    │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │      FastMCP         │
                         │       Server         │
                         └──────────┬───────────┘
                                    │
             ┌──────────────────────┼──────────────────────┐
             │                      │                      │
             ▼                      ▼                      ▼
      ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
      │    Tools    │       │   Prompts   │       │  Resources  │
      └──────┬──────┘       └─────────────┘       └─────────────┘
             │
             ▼
      ┌───────────────────────────────────────────────┐
      │              Tool Registry / Layer            │
      └──────────────────────┬────────────────────────┘
                             │
             ┌───────────────┼────────────────┐
             │               │                │
             ▼               ▼                ▼
      ┌────────────┐  ┌────────────┐  ┌────────────┐
      │ Filesystem │  │  Database  │  │ REST API  │
      │  Service   │  │  Service   │  │  Service  │
      └────────────┘  └─────┬──────┘  └────────────┘
                             │
                             ▼
                       ┌────────────┐
                       │ SQLAlchemy │
                       └─────┬──────┘
                             │
                             ▼
                       ┌────────────┐
                       │  Database  │
                       │ audit_logs │
                       └────────────┘

                    ┌─────────────────┐
                    │   AI Service    │
                    │ Provider Layer  │
                    └─────────────────┘
```

---

# 🧩 MCP Tools

The server currently exposes **14 MCP tools**.

## 📁 Filesystem Tools

| Tool | Purpose |
|---|---|
| `filesystem_read` | Read a file from the configured workspace |
| `filesystem_write` | Write content to the configured workspace |
| `filesystem_list` | List files/directories |
| `filesystem_delete` | Delete an allowed workspace file |
| `filesystem_exists` | Check whether a path exists |

---

## 🗄️ Database Tools

| Tool | Purpose |
|---|---|
| `database_query` | Execute validated read-only SQL |
| `database_execute` | Execute approved write/DDL SQL when permitted |
| `database_health` | Check database availability |

### Database Query

Example:

```json
{
  "query": "SELECT id, request_id, tool_name, status FROM audit_logs WHERE request_id = 'req-sample-002'",
  "parameters": {},
  "timeout": 30,
  "max_rows": 100
}
```

### Database Execute

Example:

```json
{
  "query": "CREATE TABLE IF NOT EXISTS mcp_test_table (id INTEGER PRIMARY KEY, message TEXT)",
  "parameters": {},
  "timeout": 30
}
```

### Database Execute Security

Database execution is intentionally controlled.

Default permission policy:

```text
QUERY    → ALLOWED
EXECUTE  → DENIED BY DEFAULT
HEALTH   → ALLOWED
```

Execution can be explicitly enabled through:

```text
DATABASE_ALLOW_EXECUTE
```

The SQL must still pass execute-query validation.

---

## 🌐 REST API

| Tool | Purpose |
|---|---|
| `rest_api_request` | Perform a validated HTTP request through the REST API service |

The REST API layer handles request validation, timeout behavior, and HTTP error handling.

---

## 🖥️ System Utilities

| Tool | Purpose |
|---|---|
| `system_current_time` | Return current system time |
| `system_info` | Return system information |
| `system_disk_usage` | Return disk usage information |
| `system_generate_hash` | Generate a cryptographic hash |

### Hash Example

Input:

```json
{
  "algorithm": "sha256",
  "input": "abc"
}
```

Output:

```text
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
```

---

## 🤖 AI

| Tool | Purpose |
|---|---|
| `ai_generate` | Generate an AI response through the configured provider layer |

AI provider configuration is managed through environment variables.

---

# 💬 MCP Prompts

The server provides **3 reusable MCP prompts**.

| Prompt | Purpose | Input |
|---|---|---|
| `system_diagnostics` | Structured system/server diagnostics | None |
| `database_analysis` | Analyze a database table | Table name |
| `incident_investigation` | Investigate an operational incident | Incident description |

### Database Analysis Example

```text
audit_logs
```

### Incident Investigation Example

```text
The database_query tool rejected a SELECT request with
UNSAFE_DATABASE_QUERY. Investigate whether the issue is
caused by SQL validation, permissions, or database availability.
```

---

# 📚 MCP Resources

The server provides **3 resources**:

| Resource | Purpose |
|---|---|
| `mcp://server/info` | Server metadata |
| `mcp://server/tools` | Registered tool information |
| `mcp://server/health` | Server/database health information |

---

# 🗄️ Database Architecture

The database layer uses **SQLAlchemy**.

The main application table is:

```text
audit_logs
```

## Audit Log Schema

| Column | Type | Description |
|---|---|---|
| `id` | INTEGER | Primary key |
| `request_id` | VARCHAR(100) | MCP request identifier |
| `client_id` | VARCHAR(100) | Client identifier |
| `tool_name` | VARCHAR(100) | Executed tool |
| `operation` | VARCHAR(100) | Operation performed |
| `status` | VARCHAR(50) | Execution status |
| `details` | TEXT | Optional details |
| `created_at` | DATETIME | Audit timestamp |

### Example Audit Record

```text
request_id : req-execute-test-001
client_id  : client-001
tool_name  : database_execute
operation  : insert
status     : success
```

---

# 🔐 Security Model

The project uses multiple security layers.

```text
Client Request
      │
      ▼
Authentication
      │
      ▼
Authorization
      │
      ▼
Input Validation
      │
      ▼
Permission Policy
      │
      ▼
Service Execution
      │
      ▼
Audit Logging
      │
      ▼
Response
```

## Database Query Security

`database_query` is read-only.

The validator rejects dangerous operations including:

```text
INSERT
UPDATE
DELETE
DROP
ALTER
TRUNCATE
CREATE
GRANT
REVOKE
EXEC / EXECUTE
CALL
```

Multiple SQL statements are also rejected.

Example rejected input:

```sql
SELECT 1; SELECT 2;
```

The validator also protects against incorrectly interpreting SQL keywords contained inside quoted string values.

---

# ⚙️ Configuration

Application configuration is centralized in:

```text
app/core/config.py
```

Configuration is loaded from environment variables and `.env`.

Important settings include:

```text
APP_NAME
APP_VERSION
APP_ENV
DEBUG

HOST
PORT

LOG_LEVEL
LOG_FILE

SECRET_KEY

DATABASE_URL
DATABASE_ALLOW_EXECUTE

AI_PROVIDER
GROQ_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY
OPENAI_API_KEY

HTTP_TIMEOUT
MAX_RETRIES
```

### ⚠️ Secrets

Never commit:

```text
.env
API keys
database credentials
secret keys
```

Use `.env.example` for safe configuration documentation.

---

# 📦 Project Structure

```text
enterprise-mcp-server/
│
├── app/
│   │
│   ├── core/
│   │   ├── config.py
│   │   ├── constants.py
│   │   ├── logger.py
│   │   └── ...
│   │
│   ├── database/
│   │   ├── models.py
│   │   ├── session.py
│   │   └── ...
│   │
│   ├── server/
│   │   ├── mcp_server.py
│   │   ├── registry.py
│   │   ├── prompts.py
│   │   └── resources.py
│   │
│   ├── services/
│   │   ├── database_service.py
│   │   ├── filesystem_service.py
│   │   ├── rest_api_service.py
│   │   └── ...
│   │
│   └── tools/
│       ├── ai/
│       ├── database/
│       ├── filesystem/
│       ├── rest_api/
│       └── system/
│
├── tests/
│   ├── unit/
│   └── integration/
│
├── docs/
│   ├── api.md
│   ├── architecture.md
│   ├── database.md
│   ├── deployment.md
│   ├── security.md
│   └── tool-reference.md
│
├── data/
├── logs/
│
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md
```

---

# 🛠️ Installation

## 1. Clone the Repository

```bash
git clone <your-repository-url>
cd enterprise-mcp-server
```

## 2. Create Virtual Environment

### Windows

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
```

### Linux / macOS

```bash
python -m venv .venv
source .venv/bin/activate
```

## 3. Install Dependencies

Install the dependencies defined by the project configuration.

## 4. Configure Environment

Copy:

```text
.env.example
```

to:

```text
.env
```

Then configure the required values.

---

# ▶️ Running the Server

The primary server module is:

```text
app/server/mcp_server.py
```

### Verify Server Initialization

```powershell
python -c "from app.server.mcp_server import initialize_server; initialize_server(); print('Server initialization successful')"
```

Expected final message:

```text
MCP server initialized successfully.
Server initialization successful
```

### Start the Server

Run the server using the project's configured server command.

---

# 🧪 Testing

Run the complete test suite:

```powershell
pytest -v
```

## Final Verified Result

```text
101 passed
```

The test suite covers areas including:

- Safe database queries
- Unsafe query rejection
- Multiple SQL statement rejection
- Database permission policy
- Execute permission behavior
- Database configuration
- Query result serialization
- Database persistence
- Audit logging
- Authentication
- Authorization
- Tool behavior
- Service behavior

---

# 🔎 MCP Inspector Verification

The project was tested using **MCP Inspector**.

Verification includes:

### Tools

```text
14 tools
```

### Prompts

```text
3 prompts
```

### Resources

```text
3 resources
```

The Inspector was used to verify operations including:

- `database_query`
- `database_execute`
- `database_health`
- `ai_generate`
- `rest_api_request`
- system utilities

---

# 🧾 Example End-to-End Database Workflow

### 1. Create a test table

```json
{
  "query": "CREATE TABLE IF NOT EXISTS mcp_test_table (id INTEGER PRIMARY KEY, message TEXT)",
  "parameters": {},
  "timeout": 30
}
```

### 2. Insert a record

```json
{
  "query": "INSERT INTO mcp_test_table (message) VALUES ('MCP test record')",
  "parameters": {},
  "timeout": 30
}
```

### 3. Query the record

```json
{
  "query": "SELECT id, message FROM mcp_test_table",
  "parameters": {},
  "timeout": 30,
  "max_rows": 100
}
```

This demonstrates the complete:

```text
Execute → Persist → Query
```

workflow.

---

# 📊 Project Metrics

| Metric | Result |
|---|---:|
| MCP Tools | **14** |
| MCP Prompts | **3** |
| MCP Resources | **3** |
| Test Cases | **101 passed** |
| Database Tables | `audit_logs` + test tables |
| Tool Families | **5** |
| Architecture | Layered / Modular |

---

# 📖 Documentation

Detailed documentation is available in the `docs/` directory:

- [`docs/api.md`](docs/api.md)
- [`docs/architecture.md`](docs/architecture.md)
- [`docs/database.md`](docs/database.md)
- [`docs/deployment.md`](docs/deployment.md)
- [`docs/security.md`](docs/security.md)
- [`docs/tool-reference.md`](docs/tool-reference.md)

---

# 🚧 Future Improvements

The current implementation is complete for the project scope.

Potential future enhancements:

- Production database migrations
- PostgreSQL deployment
- Docker / container deployment
- CI/CD pipeline
- Metrics and distributed tracing
- More granular per-client database permissions
- Parameterized MCP resource templates
- Expanded integration testing
- Production monitoring
- Additional AI provider abstractions

These are optional extensions rather than current project requirements.

---

# 🎯 What This Project Demonstrates

This project demonstrates practical experience with:

- Model Context Protocol
- FastMCP
- Python backend architecture
- API/service design
- Database engineering
- SQL security
- Permission systems
- Authentication and authorization
- Audit logging
- REST API integration
- AI integration
- Environment-based configuration
- Automated testing
- MCP Inspector
- Modular software design

---

# 👤 Author

**ILA**

Enterprise MCP Server — modular MCP tooling, security controls, database integration, AI integration, prompts, resources, and automated testing.

---

# 📄 License

Add the project's intended license here before publishing the repository publicly.