CMAP MCP Server

A Model Context Protocol (MCP) server that provides natural language access to CMAP Construction Management API data through Claude Desktop.

🚀 Features

• Natural Language Queries: Ask questions about your CMAP data in plain English
• Comprehensive API Coverage: Access companies, projects, users, contacts, and detailed financial data
• Relationship Intelligence: Built-in understanding of data relationships and foreign keys
• Business Intelligence: Complex multi-step queries for financial analysis and reporting
• Real-time Data: Live connection to CMAP sandbox and production environments

📋 What You Can Query

Business Data

• Companies: 365+ construction companies and organizations
• Projects: Project portfolios with financial details, status, and team assignments
• Users: Team members with roles (Clinical Safety Officers, Project Managers, etc.)
• Contacts: Business contacts organized by company
• Financial Data: Project values, budgets, completion percentages

Example Queries

"How much total project value has Stuart Harrison managed?"

"Show me all NHS organizations and their active projects"

"Who are the Clinical Safety Officers and what projects are they working on?"

"Which projects are over £50,000 in value?"

"Find contacts at Google UK Limited"

🛠 Installation

Option 1: Use with npx (Recommended)

npx @shopp/cmap-mcp-server

Option 2: Global Installation

npm install -g @shopp/cmap-mcp-server
cmap-mcp-server

Option 3: Local Development

git clone https://github.com/shopp/cmap-mcp-server.git
cd cmap-mcp-server
npm install
npm run build
npm start

⚙️ Configuration

Environment Variables

Create a .env file or set environment variables:

CMAP_CLIENT_ID=your-cmap-client-id
CMAP_CLIENT_SECRET=your-cmap-client-secret
CMAP_TENANT_ID=your-cmap-tenant-id
CMAP_BASE_URL=https://api.cmap-sandbox.com  # or production URL

Claude Desktop Setup

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "cmap": {
      "command": "npx",
      "args": ["-y", "@shopp/cmap-mcp-server"],
      "env": {
        "CMAP_CLIENT_ID": "your-client-id",
        "CMAP_CLIENT_SECRET": "your-client-secret", 
        "CMAP_TENANT_ID": "your-tenant-id",
        "CMAP_BASE_URL": "https://api.cmap-sandbox.com"
      }
    }
  }
}

📊 Available Tools

| Tool | Description | Parameters | |------|-------------|------------| | get_companies | Retrieve company directory | page, per_page | | get_projects | Get project listings with filters | page, per_page, status, query | | get_project | Detailed project financial data | project_id (required) | | get_users | Team member directory | page, per_page | | get_contacts | Contact directory | page, per_page, company_id | | health_check | Verify API connectivity | None |

🔗 Data Relationships

The server includes built-in intelligence about CMAP data relationships:

• Companies ↔ Projects: companies.id = projects.CompanyID
• Projects ↔ Users: projects.Owner/ProjectManager = users.firstname + lastname
• Companies ↔ Contacts: companies.id = contacts.companyId

💡 Usage Examples

Financial Analysis

"Calculate the total project value for all Clinical Safety Officers"

Business Intelligence

"Show me the top 5 companies by total project value and their key contacts"

Team Management

"What's the workload distribution among project managers?"

Relationship Queries

"Find all NHS projects over £30k and show me the project teams"

🏗 Architecture

Built using:

• MCP SDK: Official Model Context Protocol implementation
• TypeScript: Type-safe development
• Node.js: Cross-platform runtime
• OAuth2: Secure CMAP API authentication

🔒 Authentication

Uses OAuth2 Client Credentials flow with:

• Grant Type: client_credentials
• Scope: api_access
• Token Management: Automatic refresh and caching

📈 Performance

• Fast Integration: 80% faster than traditional API development (3-5 days vs 4-6 weeks)
• Efficient Queries: Smart relationship mapping reduces API calls
• Caching: Token caching and reuse for optimal performance

🛡 Security

• Environment variable configuration
• No credentials stored in code
• Secure OAuth2 implementation
• Production-ready error handling

📝 Development

Prerequisites

• Node.js 18+
• CMAP API credentials
• TypeScript knowledge (optional)

Local Development

git clone https://github.com/shopp/cmap-mcp-server.git
cd cmap-mcp-server
npm install
cp .env.example .env  # Add your credentials
npm run dev

Building

npm run build

Testing

npm test

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• Issues: GitHub Issues
• Email: [email protected]
• Website: ethos.co.im

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• CMAP Construction Management Platform
• Claude AI Assistant

Made with ❤️ by ETHOS Digital Health Team