PacketFence MCP Server

A dynamic Model Context Protocol (MCP) server that provides AI assistants with secure access to PacketFence network access control system APIs. This server automatically adapts to different PacketFence versions and deployment stages without requiring code changes.

🚀 Features

• 🔄 Dynamic API Discovery: Automatically loads and parses PacketFence OpenAPI specifications from GitHub
• 📦 Version Adaptive: Supports PacketFence 14.0+ with automatic version detection
• 🔐 Secure Authentication: Session-based authentication with automatic token refresh
• ⚙️ Deployment Stage Aware: Adapts interface based on pre-configured vs post-configured deployments
• 🛠️ Complete CRUD Operations: Exposes GET, POST, PUT, DELETE operations as MCP resources and tools
• ✅ Schema Validation: Dynamic request/response validation using OpenAPI schemas
• 🏗️ Zero Maintenance: No hardcoded version-specific logic - adapts automatically to PacketFence changes
• 📊 Comprehensive Logging: Structured logging with performance metrics and audit trails
• 🧪 Dynamic Testing: OAS-based test coverage ensuring ALL endpoints are validated
• 🔍 Endpoint Coverage: Real-time validation that all API endpoints are properly exposed

📋 Prerequisites

• Node.js: Version 18.0.0 or higher
• PacketFence: Version 14.0 or higher
• Network Access: Access to GitHub (for OpenAPI spec fetching) and PacketFence API endpoint

📦 Installation

Install from npm

npm install -g @packetfence/mcp-server@latest

Install from Source (Current Method)

git clone https://github.com/inverse-inc/packetfence-mcp.git
cd packetfence-mcp
npm install
npm link  # Makes packetfence-mcp command available globally

⚡ Quick Start

1. Verify PacketFence Setup

Ensure your PacketFence installation has:

• System API user configured
• conf/unified_api_system_pass file with system password
• API accessible at https://localhost:1443 (default)

2. Run the MCP Server

# Using global installation
packetfence-mcp

# Using npx
npx @packetfence/mcp-server

# From source
npm start

3. Configure Your AI Assistant

Claude Code (Recommended)

Method 1: Install from npm (Recommended):

# Install from npm
npm install -g @packetfence/mcp-server

# Add to Claude Code
claude mcp add packetfence packetfence-mcp

Method 2: Install from source:

# Install from source and link globally
git clone https://github.com/inverse-inc/packetfence-mcp.git
cd packetfence-mcp
npm install
npm link

# Add to Claude Code
claude mcp add packetfence packetfence-mcp

Claude Desktop

Add the MCP server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "packetfence": {
      "command": "packetfence-mcp",
      "args": []
    }
  }
}

Other MCP Clients

# Connect via stdio
packetfence-mcp

🔧 Configuration

The server automatically detects configuration from your PacketFence installation:

• Version: Read from conf/pf-release
• Deployment Stage: Detected from conf/pf.conf
• System Password: Read from conf/unified_api_system_pass
• API Endpoint: Defaults to https://localhost:1443

Environment Variables

🛠️ Usage Examples

Once connected to an AI assistant, you can perform PacketFence operations:

Node Management

"Show me all network nodes"
"Create a new node with MAC 00:11:22:33:44:55"
"Update node 00:11:22:33:44:55 status to registered"
"Delete node with MAC 00:11:22:33:44:55"

User Management

"List all PacketFence users"
"Create a new user with username 'john.doe'"
"Show user details for 'john.doe'"

Security Events

"Show recent security events"
"Close security event ID 12345"

System Information

"Show PacketFence system status"
"Display current configuration"

🏗️ Architecture

Dynamic Components

1. PacketFence Detector: Detects version and deployment stage
2. OAS Manager: Fetches and caches OpenAPI specifications
3. OAS Parser: Parses endpoints with comprehensive audit logging
4. Auth Manager: Handles PacketFence API authentication
5. MCP Generator: Dynamically creates MCP resources and tools with coverage validation
6. Schema Validator: Validates requests/responses against schemas
7. Logger: Structured logging with performance metrics and correlation IDs

Supported Operations

• Resources (GET operations): Read-only access to PacketFence data
• Tools (POST/PUT/DELETE operations): Modify PacketFence configuration
• Bulk Operations: Automatically split into individual operations
• Error Handling: Comprehensive error reporting with context

🧪 Development

Setup Development Environment

git clone https://github.com/inverse-inc/packetfence-mcp.git
cd packetfence-mcp
npm install

Run Tests

# Run all tests (excludes integration tests)
npm test

# Run all tests including integration tests
npm run test:all

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- auth-manager.test.js

# Run integration tests only
npm run test:integration

Build and Test

# Check project status
make status

# Run full build pipeline
make build

# Run tests with coverage
make test-coverage

Available Make Targets

make help           # Show all available targets
make install        # Install dependencies
make test           # Run test suite
make build          # Full build pipeline (install + lint + test)
make lint           # Run ESLint code quality checks
make version-check  # Check version synchronization
make status         # Show comprehensive project status
make clean          # Clean build artifacts and caches

🔒 Security

• No Credentials Stored: System password read from PacketFence configuration
• Session Management: Automatic token refresh and session validation
• HTTPS Only: Secure communication with PacketFence API
• Input Validation: All inputs validated against OpenAPI schemas
• Error Sanitization: Sensitive information filtered from error messages

🐛 Troubleshooting

Common Issues

Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:1443

• Verify PacketFence API is running
• Check firewall settings
• Ensure correct API URL configuration

Authentication Failed

Error: Invalid credentials for system user

• Verify conf/unified_api_system_pass file exists and is readable
• Check system user configuration in PacketFence

Version Detection Failed

Error: Could not parse version from pf-release file

• Ensure PacketFence is properly installed
• Check conf/pf-release file exists

OpenAPI Fetch Failed

Error: Failed to fetch OAS for version X.Y

• Verify internet connectivity
• Check if PacketFence version has maintenance branch on GitHub

Debug Mode

Enable verbose logging:

# Enable debug logging
LOG_LEVEL=debug packetfence-mcp

# Enable JSON structured logging
LOG_FORMAT=json packetfence-mcp

# Log to file
LOG_FILE=/tmp/packetfence-mcp.log packetfence-mcp

# Combined debugging
LOG_LEVEL=debug LOG_FORMAT=json LOG_FILE=/tmp/debug.log packetfence-mcp

🤝 Contributing

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

Development Guidelines

• Follow existing code style (ESLint configuration provided)
• Add tests for new features (prefer dynamic OAS-based tests)
• Update documentation as needed
• Ensure all tests pass before submitting PR
• Use structured logging instead of console statements
• Follow the guidelines in CLAUDE.md for LLM development practices

📄 License

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

🔗 Links

• PacketFence Documentation
• Model Context Protocol
• PacketFence GitHub
• Issue Tracker

📞 Support

• Documentation: PacketFence Docs
• Community: PacketFence Discourse
• Issues: GitHub Issues
• Commercial Support: Inverse Inc.

Note: This MCP server is designed to run on the same machine as PacketFence for security and performance reasons. Remote deployments may require additional configuration and security considerations.