ProfRandom92/comptext-mcp-server

🚀 CompText MCP Server

Token-efficient DSL server for MCP, REST, and mobile agents

CompText compiles verbose instructions into a compact DSL to cut LLM token usage by up to 90–95%. This repository ships a production-ready MCP server, REST gateway, and a mobile automation agent.

Table of Contents

• Overview
• Features
• Architecture
• Prerequisites
• Quick Start
• Configuration
• Usage
  • MCP Server
  • REST API
  • Mobile Agent CLI
• Testing & Linting
• Documentation
• Contributing
• Security
• License

Overview

CompText MCP Server exposes the CompText DSL through:

• MCP for native tool access (Claude Desktop, Cursor, etc.)
• REST for HTTP clients (Perplexity, ChatGPT API-style callers)
• Mobile agent for Android automation with minimal tokens

All services share the same validation, caching, metrics, and security hardening described in .

Features

• Token-efficient DSL with caching and input validation
• Dual interfaces: MCP server and REST wrapper
• Mobile agent with Ollama/Cloud modes and Prometheus metrics
• Rate limiting, sanitization, and structured logging
• Docker support plus Railway/render configs
• GitHub repository automation: Audit, auto-merge PRs, and manage default branches

Architecture

Client (MCP / REST / Mobile) -> CompText Server -> Data Source (Local JSON or Notion)
                                   |-> Validation & rate limiting
                                   |-> Metrics & logging
                                   |-> Caching layer

Data Sources

The server supports two data source modes:

• Local JSON (default): Uses data/codex.json for fast, offline access
• Notion API: Uses Notion database for cloud-based content management

Switch between modes using the COMPTEXT_DATA_SOURCE environment variable.

Prerequisites

• Python 3.10+
• (Optional) Notion API token if using Notion as data source
• Recommended: virtualenv

Quick Start

git clone https://github.com/ProfRandom92/comptext-mcp-server.git
cd comptext-mcp-server

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate

pip install -e .[rest,mobile]
cp .env.example .env

# Option 1: Use local JSON (default, no additional config needed)
python -m comptext_mcp.server

# Option 2: Use Notion API (edit .env first)
# Set COMPTEXT_DATA_SOURCE=notion
# Fill in NOTION_API_TOKEN and COMPTEXT_DATABASE_ID
python -m comptext_mcp.server

# (Optional) Start REST API
python rest_api_wrapper.py

Configuration

All configuration uses environment variables (see ):

Data Source Configuration

• COMPTEXT_DATA_SOURCE – Data source: "local" (default) or "notion"
• COMPTEXT_CODEX_PATH – Path to local JSON file (default: "data/codex.json")

Notion API Configuration (only if using Notion)

• NOTION_API_TOKEN – Notion API token
• COMPTEXT_DATABASE_ID – Notion database ID

Other Configuration

• GITHUB_TOKEN – GitHub API token (for automation features)
• HOST / PORT – REST server host/port
• LOG_LEVEL – Logging level

Usage

MCP Server

Add to your MCP client (example for Claude Desktop):

Using Local JSON (default):

{
  "mcpServers": {
    "comptext-codex": {
      "command": "python3",
      "args": ["-m", "comptext_mcp.server"],
      "cwd": "/path/to/comptext-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/comptext-mcp-server/src",
        "COMPTEXT_DATA_SOURCE": "local",
        "COMPTEXT_CODEX_PATH": "data/codex.json"
      }
    }
  }
}

Using Notion API:

{
  "mcpServers": {
    "comptext-codex": {
      "command": "python3",
      "args": ["-m", "comptext_mcp.server"],
      "cwd": "/path/to/comptext-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/comptext-mcp-server/src",
        "COMPTEXT_DATA_SOURCE": "notion",
        "NOTION_API_TOKEN": "your_token",
        "COMPTEXT_DATABASE_ID": "0e038c9b52c5466694dbac288280dd93"
      }
    }
  }
}

REST API

python rest_api_wrapper.py
curl http://localhost:8000/health

See for endpoints, rate limits, and examples.

Mobile Agent CLI

comptext-mobile run "Open Chrome and search for weather" --steps 10
comptext-mobile status
comptext-mobile screenshot --output screen.png

Configure via environment or a config file; details in .

Testing & Linting

pip install -e .[dev]
pytest
black . && flake8 && mypy

Documentation

Contributing

We welcome issues and PRs. Please see and follow the .

Security

Report vulnerabilities via . The project uses input validation, rate limiting, and CodeQL scanning (see CI).

License

MIT © ProfRandom92