npm package: @superadnim/companies-graph-mcp-server
Description: MCP server for building and visualizing company relationship graphs using Companies House API
Author: CG Labs
Latest version: 1.0.8

# Companies Graph MCP Server

An MCP (Model Context Protocol) server that builds and visualizes company relationship networks using the Companies House API. This server creates interactive graph databases showing relationships between companies, officers, and persons with significant control (PSCs).

## 🎯 Status: Production Ready ✅

**Latest Version**: `v1.0.5` - All known issues resolved!

- ✅ **Claude Desktop Integration**: Seamless MCP connection with clean JSON communication
- ✅ **Web Visualization**: Interactive browser interface with automatic port detection  
- ✅ **Zero Configuration**: Works out-of-the-box with simple NPX command
- ✅ **Complete Network Analysis**: Successfully maps company relationships, officers, and PSCs

## Features

- 🔍 **Company Search**: Search for UK companies by name or registration number
- 📊 **Network Building**: Automatically build relationship graphs showing company connections
- 🌐 **Interactive Visualization**: Web-based graph visualization with real-time updates
- 🔒 **Security First**: Built with enterprise-grade security practices
- 📁 **Multiple Export Formats**: Export data as JSON, CSV, or GraphML
- ⚡ **Zero-Friction Deployment**: Run instantly with NPX, no installation required

## Quick Start

```bash
# Set your Companies House API key
export COMPANIES_HOUSE_API_KEY=xxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxx

# Run the server
npx @superadnim/companies-graph-mcp-server
```

## Installation

### Option 1: NPX (Recommended)
No installation required! Simply run:
```bash
npx @superadnim/companies-graph-mcp-server
```

### Option 2: Global Installation
```bash
npm install -g @superadnim/companies-graph-mcp-server
companies-graph-mcp
```

### Option 3: Local Development
```bash
git clone https://github.com/CG-Labs/Companies-House-Graph-MCP.git
cd Companies-House-Graph-MCP
npm install
npm run build
npm start
```

## Configuration

### Environment Variables

Create a `.env` file (see `.env.example`):

```env
# Required
COMPANIES_HOUSE_API_KEY=your-api-key-here

# Optional - Server Configuration
PORT=3000
WEB_UI_PORT=8080

# Optional - Neo4j Database (only needed for persistent storage)
# Most users should omit these - the server works great without Neo4j!
# NEO4J_URI=bolt://localhost:7687
# NEO4J_USER=neo4j
# NEO4J_PASSWORD=password

# Optional - Security Configuration
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

# Optional - Logging
LOG_LEVEL=info
```

### Claude Desktop Configuration

Add to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "companies-graph": {
      "command": "npx",
      "args": ["@superadnim/companies-graph-mcp-server"],
      "env": {
        "COMPANIES_HOUSE_API_KEY": "xxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxx"
      }
    }
  }
}
```

Location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Claude Code Configuration

```bash
# Add the MCP server
claude-code config add-mcp-server companies-graph npx @superadnim/companies-graph-mcp-server

# Set the API key
export COMPANIES_HOUSE_API_KEY=your-api-key-here
```

### Augment.io Configuration

1. Open Augment.io settings
2. Navigate to MCP Servers
3. Add new server with command: `npx @superadnim/companies-graph-mcp-server`
4. Configure environment variable:
   - Name: `COMPANIES_HOUSE_API_KEY`
   - Value: `xxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxx`

## Available Tools

### 1. search_company
Search for companies by name or registration number.

**Parameters:**
- `query` (required): Company name or registration number
- `limit` (optional): Maximum results (default: 10)

**Example:**
```
Search for: "OpenAI"
```

### 2. get_company_details
Get detailed information about a specific company.

**Parameters:**
- `companyNumber` (required): The company registration number

**Example:**
```
Get details for company: "13448826"
```

### 3. build_company_network
Build a network graph of company relationships including officers, PSCs, and related companies.

**Parameters:**
- `companyNumber` (required): Starting company number
- `depth` (optional): Relationship depth (default: 2)
- `includeInactive` (optional): Include dissolved companies (default: false)

**Example:**
```
Build network for company "13448826" with depth 2
```

### 4. visualize_graph
Open web browser to visualize the company network graph.

**Parameters:**
- `companyNumber` (optional): Company to center on
- `layout` (optional): Graph layout - "force", "hierarchical", or "circular" (default: "force")

**Example:**
```
Visualize the graph with force layout
```

### 5. export_graph_data
Export the graph data in various formats.

**Parameters:**
- `format` (required): Export format - "json", "csv", or "graphml"

**Example:**
```
Export graph as JSON
```

## Resources

The server provides access to:

### graph://current
The currently loaded company network graph data.

### graph://statistics
Statistics about the current graph including node counts, edge counts, and central nodes.

## Database Storage Modes

The server supports two storage modes:

### 🧠 In-Memory Mode (Default)
- **Zero setup required** - works immediately after installation
- Data stored in JavaScript Maps for ultra-fast access
- Perfect for exploration, testing, and most production use cases
- Temporary storage (data cleared on server restart)
- **Recommended for most users**

### 🗃️ Neo4j Mode (Optional)
- Requires a running Neo4j database instance
- Persistent storage across server restarts
- Advanced graph algorithms and Cypher queries
- Better for enterprise deployments with massive datasets
- **Only needed for specialized use cases**

**The server automatically uses in-memory mode unless Neo4j credentials are provided.**

## Security Features

### Authentication & Authorization
- Secure API key management through environment variables
- Support for Azure AD integration (when deployed to Azure)
- OAuth 2.1 framework compliance

### Rate Limiting
- Configurable request limits per time window
- Prevents API abuse and ensures fair usage
- Default: 100 requests per 15 minutes

### Data Protection
- All API communications over HTTPS
- Input validation and sanitization
- Secure credential storage
- No hardcoded secrets

### Content Security
- Helmet.js for secure HTTP headers
- CORS protection
- XSS prevention
- CSP (Content Security Policy) enforcement

## Web UI Features

The interactive visualization includes:

- **Real-time Updates**: WebSocket connection for live graph updates
- **Interactive Navigation**: Pan, zoom, and click nodes for details
- **Search Functionality**: Find specific companies or people
- **Multiple Layouts**: Force-directed, hierarchical, or circular layouts
- **Node Information**: Click any node to see detailed information
- **Export Options**: Download graph data in multiple formats

### Graph Legend

- 🟢 **Green**: Companies
- 🔵 **Blue**: Persons
- 🟠 **Orange**: Officers
- 🟣 **Purple**: Persons with Significant Control (PSCs)

## Development

### Prerequisites
- Node.js 18.0.0 or higher
- TypeScript 5.0 or higher
- Companies House API key

### Setup
```bash
# Clone the repository
git clone https://github.com/CG-Labs/Companies-House-Graph-MCP.git
cd Companies-House-Graph-MCP

# Install dependencies
npm install

# Run in development mode
npm run dev
```

### Testing
```bash
# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format
```

### Building
```bash
# Build for production
npm run build

# Build and run
npm run build && npm start
```

## Deployment

### Azure Deployment

For enterprise deployment with Azure AD integration:

1. Create an Azure App Service
2. Configure environment variables
3. Enable Azure AD authentication
4. Deploy using GitHub Actions or Azure DevOps

### Docker Deployment

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000 8080
CMD ["npm", "start"]
```

## Troubleshooting

### Common Issues

**API Key Issues**
- Ensure your Companies House API key is valid
- Check that the environment variable is set correctly
- Verify the key has not expired

**Connection Issues**
- Check firewall settings for ports 3000 and 8080
- Ensure WebSocket connections are allowed
- Verify Companies House API is accessible

**Graph Not Loading**
- Check browser console for errors
- Ensure data has been fetched using `build_company_network`
- Verify WebSocket connection is established

### Debug Mode

Enable debug logging:
```bash
export LOG_LEVEL=debug
```

## API Rate Limits

Companies House API has the following limits:
- 600 requests per 5 minutes
- Some endpoints have additional restrictions

This server implements intelligent rate limiting to stay within these bounds.

## Troubleshooting

### Common Issues ✅ RESOLVED

#### Issue: "Unexpected token" or JSON parsing errors in Claude Desktop
**Status**: ✅ **FIXED in v1.0.4**  
**Cause**: Colored log output corrupting JSON communication  
**Solution**: Automatic environment detection disables colors in MCP mode

#### Issue: Web visualization shows "No data loaded"  
**Status**: ✅ **FIXED in v1.0.5**  
**Cause**: Port conflicts preventing web server startup  
**Solution**: Automatic port detection with fallback (8080 → 8081 → 8082...)

### Current Troubleshooting Steps

1. **Update to latest version**:
   ```bash
   npx @superadnim/companies-graph-mcp-server@latest
   ```

2. **Verify API key**:
   ```bash
   curl -H "Authorization: YOUR_API_KEY" https://api.company-information.service.gov.uk/
   ```

3. **Check logs**:
   - Claude Desktop: `~/Library/Logs/Claude/mcp-server-companies-graph.log`
   - Enable debug: Set `LOG_LEVEL=debug` in environment

4. **Test installation**:
   ```bash
   # Run the test script included in the package
   npx @superadnim/companies-graph-mcp-server --test
   ```

### Getting Help

If you encounter issues:
1. Check the [TROUBLESHOOTING_NPX.md](./TROUBLESHOOTING_NPX.md) guide
2. Review recent [GitHub Issues](https://github.com/CG-Labs/Companies-House-Graph-MCP/issues)
3. Create a new issue with:
   - Node.js version (`node --version`)
   - NPM version (`npm --version`)
   - Operating system
   - Error logs

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - see LICENSE file for details

## Support

- **Issues**: [GitHub Issues](https://github.com/CG-Labs/Companies-House-Graph-MCP/issues)
- **Documentation**: [Full Documentation](https://github.com/CG-Labs/Companies-House-Graph-MCP#readme)
- **Companies House API**: [developer.company-information.service.gov.uk](https://developer.company-information.service.gov.uk)

## Roadmap

### ✅ Completed (v1.0.5)
- [x] Interactive web visualization  
- [x] Real-time WebSocket updates
- [x] Multiple export formats (JSON, CSV, GraphML)
- [x] Automatic port detection
- [x] Clean MCP protocol integration
- [x] Comprehensive error handling

### 🚀 Upcoming Features
- [ ] Neo4j database persistence
- [ ] Advanced graph algorithms (PageRank, community detection)
- [ ] Bulk company import via CSV/Excel
- [ ] Historical data tracking and timeline view
- [ ] International company support (EU, US)
- [ ] Advanced filtering options (date ranges, company types)
- [ ] GraphQL API endpoint
- [ ] Export to popular analysis tools (Gephi, Cytoscape)

## Acknowledgments

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol)
- [Companies House API](https://developer.company-information.service.gov.uk)
- [Vis.js Network](https://visjs.org)
- [Express](https://expressjs.com)
- [TypeScript](https://www.typescriptlang.org)