🚀 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 OPTIMIZATION_SUMMARY.md.

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 .env.example):

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 docs/API.md 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 docs/mobile-agent.md.

Testing & Linting

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

Documentation

• Quick Start

• API Reference

• Deployment Guide

• GitHub Automation

• FAQ

• Optimization Summary

Contributing

We welcome issues and PRs. Please see CONTRIBUTING.md and follow the CODE_OF_CONDUCT.md.

Security

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

License

MIT © ProfRandom92