# Enterprise Procurement MCP Server

A production-ready MCP (Model Context Protocol) server for Enterprise Procurement Intelligence. Provides AI-powered procurement policy compliance, document generation, supplier management, budget verification, and analytics through standardized MCP tools.

## Features

- **Policy & Compliance**: RAG-powered search over procurement laws, regulations, SOPs, and templates
- **Procurement Planning**: Create, validate, and review procurement plans
- **Document Generation**: Generate tender documents, RFQs, RFPs, contracts
- **Supplier Management**: Risk assessment, due diligence, performance scoring
- **Budget Verification**: Real-time budget availability checks and commitment tracking
- **Three-Way Matching**: PO-GRN-Invoice matching with variance detection
- **Spend Analytics**: Category, supplier, and department spend analysis
- **Market Intelligence**: Price comparison, trend forecasting, anomaly detection
- **Procurement Audit**: Compliance checks, red flag detection, approval trail verification
- **ERP Integration**: Extensible adapter framework for SAP, Oracle, Dynamics, Odoo
- **Document Management**: Support for PDF, DOCX, TXT, Markdown, HTML, CSV, XLSX

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                        MCP Client (OpenCode, Claude, etc.)         │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ MCP Protocol (stdio)
┌──────────────────────────────▼──────────────────────────────────────┐
│                     MCP Server (StdioServerTransport)               │
│  ┌────────────────────────────────────────────────────────────────┐│
│  │                    Tool Router                                  ││
│  │  tools/list  |  tools/call  |  Zod Validation  |  Auth/RBAC   ││
│  └────────────────────────────────────────────────────────────────┘│
┌─────────┬──────────┬──────────┬─────────┬──────────┬──────────────┐│
│ Policy  │ Planning │ Tender   │ RFQ/RFP │ Supplier │ Bid Eval     ││
│ & Comp  │          │ Generator│ Author  │ Risk     │              ││
├─────────┼──────────┼──────────┼─────────┼──────────┼──────────────┤│
│ Contract│ Req/PO   │ Budget   │ 3-Way   │ Perform  │ Spend/Market││
│ Review  │          │ Verify   │ Match   │ Analytics│ Analytics    ││
├─────────┴──────────┴──────────┴─────────┴──────────┴──────────────┤│
│                    RAG Pipeline (pgvector)                         ││
│  Document Ingest → Chunk → Embeddings → Vector Search → Citations ││
├───────────────────────────────────────────────────────────────────┤│
│                    Integration Adapters                            ││
│  SAP │ Oracle │ Dynamics │ Odoo │ e-Proc │ SharePoint │ MinIO/S3  ││
└───────────────────────────────────────────────────────────────────-┘
```

## Quick Start

### Local Development

```bash
# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your configuration

# Start PostgreSQL and Redis
docker compose up -d postgres redis

# Run database migrations
npm run db:migrate

# Seed sample data
npm run db:seed

# Start the MCP server
npm run dev
```

### Using Docker

```bash
# Start all services
docker compose up -d

# Run migrations
docker compose exec app npx prisma migrate deploy

# Seed data
docker compose exec app npm run db:seed
```

## Connecting from MCP Clients

### OpenCode Configuration

Add to your opencode.json:

```json
{
  "mcpServers": {
    "procurement": {
      "command": "node",
      "args": ["path/to/procurement-mcp-server/dist/server.js"],
      "env": {
        "API_KEY": "your-api-key",
        "DATABASE_URL": "postgresql://...",
        "REDIS_URL": "redis://..."
      }
    }
  }
}
```

### Claude Desktop Configuration

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "procurement": {
      "command": "node",
      "args": ["path/to/procurement-mcp-server/dist/server.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}
```

### VS Code / Cursor

Configure the MCP server in the AI extension settings using the same command format.

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |
| `OPENAI_API_KEY` | OpenAI API key for embeddings | Optional |
| `EMBEDDING_PROVIDER` | Embedding provider (openai/local/mock) | `mock` |
| `API_KEY` | MCP server API key | `dev-key` |
| `STORAGE_PROVIDER` | Document storage (local/minio/s3) | `local` |
| `LOG_LEVEL` | Logging level | `info` |

## Available MCP Tools

### Policy & Compliance
- `search_policy` - Search procurement policies and regulations
- `ask_compliance_question` - Ask compliance questions with citations
- `explain_clause` - Explain procurement clauses in plain language
- `recommend_procurement_method` - Recommend procurement method
- `generate_compliance_checklist` - Generate compliance checklist
- `compare_policy_versions` - Compare policy document versions

### Procurement Planning
- `create_procurement_plan` - Create procurement plan
- `validate_procurement_plan` - Validate plan completeness
- `generate_procurement_calendar` - Generate procurement calendar
- `forecast_procurement_needs` - Forecast procurement needs
- `review_procurement_plan_compliance` - Review plan compliance

### Tender & RFQ/RFP
- `generate_tender_document` - Generate tender document
- `generate_invitation_to_tender` - Generate ITT
- `generate_scope_of_work` - Generate SoW
- `generate_evaluation_criteria` - Generate evaluation criteria
- `generate_rfq` - Generate Request for Quotations
- `generate_rfp` - Generate Request for Proposals

### Supplier Management
- `assess_supplier_risk` - Assess supplier risk
- `verify_supplier_documents` - Verify supplier documents
- `generate_supplier_scorecard` - Generate supplier scorecard
- `check_conflict_of_interest` - Check conflicts of interest

### Budget & Finance
- `check_budget_availability` - Check budget availability
- `reserve_budget_commitment` - Reserve budget commitment
- `budget_utilization_summary` - Budget utilization summary
- `match_po_grn_invoice` - Three-way matching
- `detect_duplicate_invoice` - Detect duplicate invoices

### Contract Management
- `review_contract` - Review contract risks
- `extract_contract_clauses` - Extract all clauses
- `compare_contract_to_template` - Compare to template

### Analytics
- `spend_by_category` - Spend analysis by category
- `spend_by_supplier` - Spend analysis by supplier
- `detect_maverick_spending` - Detect maverick spending
- `get_market_price` - Get market price intelligence
- `forecast_price_trend` - Forecast price trends

### Audit
- `audit_procurement_file` - Audit procurement file
- `detect_missing_documents` - Detect missing documents
- `detect_procurement_red_flags` - Detect red flags

### Integrations
- `list_integrations` - List available integrations
- `connect_integration` - Connect to ERP system
- `fetch_vendors_from_erp` - Fetch vendors from ERP

## Example Tool Calls

```bash
# Search procurement policies
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_policy","arguments":{"query":"open tendering threshold"}}}' | node dist/server.js

# Check budget availability
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_budget_availability","arguments":{"budgetCode":"BUD-IT-2024","amount":50000}}}' | node dist/server.js

# Generate compliance checklist
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_compliance_checklist","arguments":{"procurementMethod":"Open Tendering","procurementCategory":"IT Equipment","estimatedValue":150000}}}' | node dist/server.js
```

## Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

## Project Structure

```
src/
├── server.ts                    # Entry point
├── config/env.ts               # Environment configuration
├── common/                      # Shared utilities (logger, errors, database)
├── auth/                        # Authentication & RBAC
├── mcp/                         # MCP server & tools
│   ├── index.ts                  # MCP server setup
│   └── tools/                    # Tool implementations (17 categories)
├── modules/                     # Business logic
│   ├── documents/               # Document management
│   ├── rag/                     # RAG pipeline
│   ├── embeddings/              # Embedding service abstraction
│   ├── procurement/            # Procurement planning
│   ├── suppliers/              # Supplier management
│   ├── contracts/              # Contract management
│   ├── requisitions/           # Purchase requisitions
│   ├── purchase-orders/        # Purchase orders
│   ├── budgets/                # Budget management
│   ├── invoices/               # Invoice matching
│   ├── analytics/              # Spend & market analytics
│   ├── audit/                  # Audit & compliance
│   └── integrations/           # ERP adapters
├── workers/                     # Background workers (ingestion, embedding)
└── database/                    # Database client
prisma/
├── schema.prisma               # Database schema
└── seed.ts                     # Seed data
tests/                           # Test files
docs/                            # Documentation
docker/                          # Docker configuration
```

## Security

- API key authentication with SHA-256 hashing
- Role-Based Access Control (RBAC) with granular permissions
- Input validation via Zod schemas
- SQL injection protection via Prisma ORM
- Audit logging for every tool call
- Safe file upload with type allowlist and size limits
- No secrets in code — all via environment variables
- Structured error responses (no stack traces in production)

## Production Deployment

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for production deployment guides including Docker, VPS, and Kubernetes.

## License

MIT