Package Exports

cmap-mcp-server
cmap-mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cmap-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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

📄 License

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

📞 Support

Issues: GitHub Issues
Email: stuart.harrison@ethos.co.im
Website: ethos.co.im

🙏 Acknowledgments

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

Made with ❤️ by ETHOS Digital Health Team