FairCom MCP Server

[!IMPORTANT] Developers and maintainers: use BUILD.md for build, packaging, and release instructions. This README is product and usage focused.

Connect AI assistants and LLMs to FairCom databases with explicit write controls, Linux packaging, and operational tooling.

hljs language-scss

┌─────────────────────────────────────────────────────────────┐
│  Your AI Assistant (Claude, Copilot, etc.)                  │
└────────────────────┬────────────────────────────────────────┘
                     │ MCP Protocol
                     │ (HTTP + JSON-RPC)
┌────────────────────▼────────────────────────────────────────┐
│  FairCom MCP Server                                         │
│  • Session management                                       │
│  • Write safety enforcement (confirm_write=true)            │
│  • Tool exposure control                                    │
│  • Rate limiting, observability                             │
└────────────────────┬────────────────────────────────────────┘
                     │ FairCom JSON API
                     │ (HTTP REST)
┌────────────────────▼────────────────────────────────────────┐
│  FairCom Database                                           │
│  (Edge, DB, RTG, ISAM, MQ)                                  │
└─────────────────────────────────────────────────────────────┘

Why FairCom MCP?

Open source: Apache 2.0
Operationally ready: systemd service, log rotation, health checks
Safe by default: explicit write confirmation and tool allowlisting
Broad compatibility: works with Edge, DB, RTG, ISAM, and MQ
MCP-focused: intended for Claude, Copilot, and local LLM workflows

Use Cases

1. Business Intelligence & Reporting

Let users ask natural-language questions about FairCom data.

Example: "What were our top 5 products by revenue last quarter?"

The AI assistant translates this to SQL, queries FairCom, and summarizes results with visualizations.

hljs language-python

# FairCom MCP exposes:
# sql_query(statement, params?) → fetch data
# list_tables(name_like?) → discover schema
# list_table_columns(table_name) → understand structure

2. Data Integration & ETL

Automate data pipelines that read/write to FairCom.

Example: Sync customer data from SaaS → FairCom using AI-guided transformations.

hljs language-python

# The AI assistant can:
# 1. List available tables (list_tables)
# 2. Inspect target schema (describe_table)
# 3. Execute transformations (sql_execute with confirm_write=true)
# 4. Validate results (sql_query to spot-check)

3. Operational Analytics

Real-time status monitoring and anomaly detection.

Example: "Show me any orders with payment processing delays."

hljs language-python

# FairCom MCP provides:
# - /metrics → Prometheus-compatible metrics
# - /diagnostics → System health
# - sql_query → Run diagnostic queries
# Combine for full observability loop

4. Domain-Specific AI Chatbots

Build internal tools (CRM, inventory, compliance).

Example: Chatbot for warehouse staff to check inventory levels, process returns.

hljs language-python

# Sandbox the chatbot with:
# FAIRCOM_TOOL_GROUP_ALLOWLIST=metadata,query
# (write tools disabled for read-only workflows)
#
# FAIRCOM_SQL_DENYLIST=DELETE,DROP
# (prevent destructive operations)

Quick Start (5 Minutes)

Option 1: Docker (Fastest)

hljs language-bash

# Start FairCom MCP pointing to your FairCom instance
docker run -d --name faircom-mcp \
  -p 8000:8000 \
  -e FAIRCOM_API_BASE_URL=http://faircom-host:8080 \
  -e FAIRCOM_API_USERNAME=ADMIN \
  -e FAIRCOM_API_PASSWORD=ADMIN \
  faircomteam/faircom-mcp:latest --transport http

If FairCom is running on your local host machine, use:

hljs language-bash

-e FAIRCOM_API_BASE_URL=http://host.docker.internal:8080

Option 2: Linux Package (Production)

Debian/Ubuntu:

hljs language-bash

sudo apt-get install -y ./faircom-mcp_0.1.3_all.deb
sudo systemctl enable --now faircom-mcp

RHEL/Rocky/AlmaLinux:

hljs language-bash

sudo dnf install -y ./faircom-mcp-0.1.3-1.noarch.rpm
sudo systemctl enable --now faircom-mcp

Verify it's running:

hljs language-bash

# Health check
curl -fsS http://127.0.0.1:8000/health
# Output: {"status":"healthy"}

# List available tables
curl -i -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    }
  }' | head -20

Docker Hub Usage

The official image repository is:

faircomteam/faircom-mcp

Recommended tag usage:

latest: Recommended default tag for standard users
v* tags (for example vX.Y.Z): Immutable release tags for production pinning

Pull examples:

hljs language-bash

# Default current image
docker pull faircomteam/faircom-mcp:latest

# Pin to an immutable release for production
docker pull faircomteam/faircom-mcp:vX.Y.Z

Run example (recommended default):

hljs language-bash

docker run -d --name faircom-mcp \
  -p 8000:8000 \
  -e FAIRCOM_API_BASE_URL=http://faircom-host:8080 \
  -e FAIRCOM_API_USERNAME=ADMIN \
  -e FAIRCOM_API_PASSWORD=ADMIN \
  faircomteam/faircom-mcp:latest --transport http

Notes:

Use latest for normal usage and quick evaluation.
Use release tag pins (v*) only when you need immutable version locking.
latest and v* tags are published together from the same release tag workflow.

Tutorial: Query Your First Table

Let's query FairCom using Claude or a local LLM via FairCom MCP.

Step 1: Initialize MCP Session

hljs language-bash

curl -i -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0"}
    }
  }' 2>&1 | grep -i "mcp-session-id"

# Save the session ID from the response, e.g.: abc123
SESSION_ID="abc123"

Step 2: List Tables

hljs language-bash

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }' 2>&1 | grep -A 5 "list_tables"

Step 3: Describe a Table

hljs language-bash

# Let's examine the "customers" table
curl -X POST http://127.0.0.1:8000/mcp \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "describe_table",
      "arguments": {"table_name": "customers"}
    }
  }' 2>&1 | tail -20

Step 4: Query Data

hljs language-bash

# Count customers
curl -X POST http://127.0.0.1:8000/mcp \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "sql_query",
      "arguments": {
        "statement": "SELECT COUNT(*) as total FROM customers"
      }
    }
  }' 2>&1 | tail -20

Step 5: Configure in Claude/Copilot

For Claude Desktop:

hljs language-json

{
  "mcpServers": {
    "faircom": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

For GitHub Copilot (VS Code):

hljs language-json

{
  "mcpServers": {
    "faircom": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Then ask your AI assistant: "Show me a count of customers by region" – it will use FairCom MCP to execute the query.

Configuration

Edit /etc/faircom-mcp/faircom-mcp.env (package install) or pass as environment variables (Docker):

hljs language-bash

# Required: FairCom connectivity
FAIRCOM_API_BASE_URL=https://faircom.example.com:9443
FAIRCOM_API_USERNAME=ADMIN           # or use FAIRCOM_API_TOKEN
FAIRCOM_API_PASSWORD=ADMIN

# Optional: Server binding
FAIRCOM_HTTP_HOST=0.0.0.0
FAIRCOM_HTTP_PORT=8000

# Optional: TLS
FAIRCOM_TLS_VERIFY=true              # Set to false for self-signed certs

# Optional: Safety controls
FAIRCOM_TOOL_GROUP_ALLOWLIST=metadata,query,write,admin,diagnostics
FAIRCOM_SQL_ALLOWLIST=SELECT,INSERT,UPDATE,DELETE
FAIRCOM_SQL_DENYLIST=DROP,TRUNCATE,ALTER

Available Tools

Tool	Purpose	Safety
`list_tables(name_like?)`	Discover tables	Read-only
`describe_table(table_name)`	Get columns, indexes, constraints	Read-only
`list_table_columns(table_name)`	Column names and types	Read-only
`list_table_indexes(table_name)`	Index details	Read-only
`sql_query(statement, params?)`	Execute SELECT (read-only)	Read-only
`sql_query_page(statement, params?, page, page_size)`	Paginated SELECT	Read-only
`sql_execute(statement, params?, confirm_write)`	INSERT/UPDATE/DELETE (requires `confirm_write=true`)	Write
`runtime_status()`	Health, version, diagnostics	Read-only

Observability & Operations

Health Endpoints

hljs language-bash

GET  /health       # Simple health check (JSON)
GET  /healthz      # Kubernetes-style liveness
GET  /ready        # Readiness check (JSON)
GET  /readyz       # Kubernetes-style readiness
GET  /metrics      # Prometheus-compatible metrics
GET  /diagnostics  # Human-readable diagnostics
GET  /diagnostics/json  # Machine-readable diagnostics

Logs

Package install:

hljs language-bash

journalctl -u faircom-mcp -f       # Follow logs
journalctl -u faircom-mcp --since 1h # Last hour

Docker:

hljs language-bash

docker logs -f faircom-mcp

Log Rotation

Package install includes logrotate policy:

hljs language-bash

/var/log/faircom-mcp/faircom-mcp.log {
  daily
  rotate 7
  compress
  delaycompress
  notifempty
  missingok
}

Development

See BUILD.md for building, testing, and releasing.

Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Contributing: See CONTRIBUTING.md (coming soon)

License

Licensed under the Apache License, Version 2.0. See LICENSE for terms.

Support

For FairCom-specific questions: https://www.faircom.com/support For MCP integration issues: Open a GitHub issue

Built for the FairCom community. Query with confidence. Automate with safety.

FairCom MCP Server

[!IMPORTANT] Developers and maintainers: use BUILD.md for build, packaging, and release instructions. This README is product and usage focused.

Connect AI assistants and LLMs to FairCom databases with explicit write controls, Linux packaging, and operational tooling.

hljs language-scss

┌─────────────────────────────────────────────────────────────┐
│  Your AI Assistant (Claude, Copilot, etc.)                  │
└────────────────────┬────────────────────────────────────────┘
                     │ MCP Protocol
                     │ (HTTP + JSON-RPC)
┌────────────────────▼────────────────────────────────────────┐
│  FairCom MCP Server                                         │
│  • Session management                                       │
│  • Write safety enforcement (confirm_write=true)            │
│  • Tool exposure control                                    │
│  • Rate limiting, observability                             │
└────────────────────┬────────────────────────────────────────┘
                     │ FairCom JSON API
                     │ (HTTP REST)
┌────────────────────▼────────────────────────────────────────┐
│  FairCom Database                                           │
│  (Edge, DB, RTG, ISAM, MQ)                                  │
└─────────────────────────────────────────────────────────────┘

Why FairCom MCP?

Open source: Apache 2.0
Operationally ready: systemd service, log rotation, health checks
Safe by default: explicit write confirmation and tool allowlisting
Broad compatibility: works with Edge, DB, RTG, ISAM, and MQ
MCP-focused: intended for Claude, Copilot, and local LLM workflows

Use Cases

1. Business Intelligence & Reporting

Let users ask natural-language questions about FairCom data.

Example: "What were our top 5 products by revenue last quarter?"

The AI assistant translates this to SQL, queries FairCom, and summarizes results with visualizations.

hljs language-python

# FairCom MCP exposes:
# sql_query(statement, params?) → fetch data
# list_tables(name_like?) → discover schema
# list_table_columns(table_name) → understand structure

2. Data Integration & ETL

Automate data pipelines that read/write to FairCom.

Example: Sync customer data from SaaS → FairCom using AI-guided transformations.

hljs language-python

# The AI assistant can:
# 1. List available tables (list_tables)
# 2. Inspect target schema (describe_table)
# 3. Execute transformations (sql_execute with confirm_write=true)
# 4. Validate results (sql_query to spot-check)

3. Operational Analytics

Real-time status monitoring and anomaly detection.

Example: "Show me any orders with payment processing delays."

hljs language-python

# FairCom MCP provides:
# - /metrics → Prometheus-compatible metrics
# - /diagnostics → System health
# - sql_query → Run diagnostic queries
# Combine for full observability loop

4. Domain-Specific AI Chatbots

Build internal tools (CRM, inventory, compliance).

Example: Chatbot for warehouse staff to check inventory levels, process returns.

hljs language-python

# Sandbox the chatbot with:
# FAIRCOM_TOOL_GROUP_ALLOWLIST=metadata,query
# (write tools disabled for read-only workflows)
#
# FAIRCOM_SQL_DENYLIST=DELETE,DROP
# (prevent destructive operations)

Quick Start (5 Minutes)

Option 1: Docker (Fastest)

hljs language-bash

# Start FairCom MCP pointing to your FairCom instance
docker run -d --name faircom-mcp \
  -p 8000:8000 \
  -e FAIRCOM_API_BASE_URL=http://faircom-host:8080 \
  -e FAIRCOM_API_USERNAME=ADMIN \
  -e FAIRCOM_API_PASSWORD=ADMIN \
  faircomteam/faircom-mcp:latest --transport http

If FairCom is running on your local host machine, use:

hljs language-bash

-e FAIRCOM_API_BASE_URL=http://host.docker.internal:8080

Option 2: Linux Package (Production)

Debian/Ubuntu:

hljs language-bash

sudo apt-get install -y ./faircom-mcp_0.1.3_all.deb
sudo systemctl enable --now faircom-mcp

RHEL/Rocky/AlmaLinux:

hljs language-bash

sudo dnf install -y ./faircom-mcp-0.1.3-1.noarch.rpm
sudo systemctl enable --now faircom-mcp

Verify it's running:

hljs language-bash

# Health check
curl -fsS http://127.0.0.1:8000/health
# Output: {"status":"healthy"}

# List available tables
curl -i -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    }
  }' | head -20

Docker Hub Usage

The official image repository is:

faircomteam/faircom-mcp

Recommended tag usage:

latest: Recommended default tag for standard users
v* tags (for example vX.Y.Z): Immutable release tags for production pinning

Pull examples:

hljs language-bash

# Default current image
docker pull faircomteam/faircom-mcp:latest

# Pin to an immutable release for production
docker pull faircomteam/faircom-mcp:vX.Y.Z

Run example (recommended default):

hljs language-bash

docker run -d --name faircom-mcp \
  -p 8000:8000 \
  -e FAIRCOM_API_BASE_URL=http://faircom-host:8080 \
  -e FAIRCOM_API_USERNAME=ADMIN \
  -e FAIRCOM_API_PASSWORD=ADMIN \
  faircomteam/faircom-mcp:latest --transport http

Notes:

Use latest for normal usage and quick evaluation.
Use release tag pins (v*) only when you need immutable version locking.
latest and v* tags are published together from the same release tag workflow.

Tutorial: Query Your First Table

Let's query FairCom using Claude or a local LLM via FairCom MCP.

Step 1: Initialize MCP Session

hljs language-bash

curl -i -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0"}
    }
  }' 2>&1 | grep -i "mcp-session-id"

# Save the session ID from the response, e.g.: abc123
SESSION_ID="abc123"

Step 2: List Tables

hljs language-bash

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }' 2>&1 | grep -A 5 "list_tables"

Step 3: Describe a Table

hljs language-bash

# Let's examine the "customers" table
curl -X POST http://127.0.0.1:8000/mcp \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "describe_table",
      "arguments": {"table_name": "customers"}
    }
  }' 2>&1 | tail -20

Step 4: Query Data

hljs language-bash

# Count customers
curl -X POST http://127.0.0.1:8000/mcp \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "sql_query",
      "arguments": {
        "statement": "SELECT COUNT(*) as total FROM customers"
      }
    }
  }' 2>&1 | tail -20

Step 5: Configure in Claude/Copilot

For Claude Desktop:

hljs language-json

{
  "mcpServers": {
    "faircom": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

For GitHub Copilot (VS Code):

hljs language-json

{
  "mcpServers": {
    "faircom": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Then ask your AI assistant: "Show me a count of customers by region" – it will use FairCom MCP to execute the query.

Configuration

Edit /etc/faircom-mcp/faircom-mcp.env (package install) or pass as environment variables (Docker):

hljs language-bash

# Required: FairCom connectivity
FAIRCOM_API_BASE_URL=https://faircom.example.com:9443
FAIRCOM_API_USERNAME=ADMIN           # or use FAIRCOM_API_TOKEN
FAIRCOM_API_PASSWORD=ADMIN

# Optional: Server binding
FAIRCOM_HTTP_HOST=0.0.0.0
FAIRCOM_HTTP_PORT=8000

# Optional: TLS
FAIRCOM_TLS_VERIFY=true              # Set to false for self-signed certs

# Optional: Safety controls
FAIRCOM_TOOL_GROUP_ALLOWLIST=metadata,query,write,admin,diagnostics
FAIRCOM_SQL_ALLOWLIST=SELECT,INSERT,UPDATE,DELETE
FAIRCOM_SQL_DENYLIST=DROP,TRUNCATE,ALTER

Available Tools

Tool	Purpose	Safety
`list_tables(name_like?)`	Discover tables	Read-only
`describe_table(table_name)`	Get columns, indexes, constraints	Read-only
`list_table_columns(table_name)`	Column names and types	Read-only
`list_table_indexes(table_name)`	Index details	Read-only
`sql_query(statement, params?)`	Execute SELECT (read-only)	Read-only
`sql_query_page(statement, params?, page, page_size)`	Paginated SELECT	Read-only
`sql_execute(statement, params?, confirm_write)`	INSERT/UPDATE/DELETE (requires `confirm_write=true`)	Write
`runtime_status()`	Health, version, diagnostics	Read-only

Observability & Operations

Health Endpoints

hljs language-bash

GET  /health       # Simple health check (JSON)
GET  /healthz      # Kubernetes-style liveness
GET  /ready        # Readiness check (JSON)
GET  /readyz       # Kubernetes-style readiness
GET  /metrics      # Prometheus-compatible metrics
GET  /diagnostics  # Human-readable diagnostics
GET  /diagnostics/json  # Machine-readable diagnostics

Logs

Package install:

hljs language-bash

journalctl -u faircom-mcp -f       # Follow logs
journalctl -u faircom-mcp --since 1h # Last hour

Docker:

hljs language-bash

docker logs -f faircom-mcp

Log Rotation

Package install includes logrotate policy:

hljs language-bash

/var/log/faircom-mcp/faircom-mcp.log {
  daily
  rotate 7
  compress
  delaycompress
  notifempty
  missingok
}

Development

See BUILD.md for building, testing, and releasing.

Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Contributing: See CONTRIBUTING.md (coming soon)

License

Licensed under the Apache License, Version 2.0. See LICENSE for terms.

Support

For FairCom-specific questions: https://www.faircom.com/support For MCP integration issues: Open a GitHub issue

Built for the FairCom community. Query with confidence. Automate with safety.

faircom-mcp

FairCom MCP Server

Use Cases

1. Business Intelligence & Reporting

2. Data Integration & ETL

3. Operational Analytics

4. Domain-Specific AI Chatbots

Quick Start (5 Minutes)

Option 1: Docker (Fastest)

Option 2: Linux Package (Production)

Verify it's running:

Docker Hub Usage

Tutorial: Query Your First Table

Configuration

Available Tools

Observability & Operations

Health Endpoints

Logs

Log Rotation

Development

Community

License

Support

Similar Packages

faircom-mcp

FairCom MCP Server

Use Cases

1. Business Intelligence & Reporting

2. Data Integration & ETL

3. Operational Analytics

4. Domain-Specific AI Chatbots

Quick Start (5 Minutes)

Option 1: Docker (Fastest)

Option 2: Linux Package (Production)

Verify it's running:

Docker Hub Usage

Tutorial: Query Your First Table

Configuration

Available Tools

Observability & Operations

Health Endpoints

Logs

Log Rotation

Development

Community

License

Support

Similar Packages