Skip to main content
Glama
CtrlAsistent MCP Server

CtrlAsistent MCP Server

Official
by ctrlasistent

šŸ“– CtrlAsistent MCP Server

šŸ  Overview

This is the CtrlAsistent MCP (Model Context Protocol) server, which works with any MCP client:

  • llama.cpp

  • OpenCode

  • DSH Harness

  • Pi Harness

  • Claude Desktop

  • and others

Related MCP server: Grok Bot MCP Bridge

šŸ“ Project Structure

ctrlasistent_mcp/
ā”œā”€ā”€ ctrlasistent_mcp.py           # Main server
ā”œā”€ā”€ tools_server.py               # Automatic tool discovery from tools/
ā”œā”€ā”€ skills_server.py              # Exposes skills (list_skills / read_skill)
ā”œā”€ā”€ ctrlasistent_mcp.json         # Config (mcpServers format)
ā”œā”€ā”€ .env                          # Sensitive data
ā”œā”€ā”€ core/
│   ā”œā”€ā”€ CtrlAsistent_tools.py     # Tool base class
│   └── CtrlAsistent_DocumentIndexer.py   # RAG (FAISS + BM25)
ā”œā”€ā”€ tools/                        # Tools
│   ā”œā”€ā”€ tool_weather.py
│   ā”œā”€ā”€ tool_websearch.py
│   ā”œā”€ā”€ tool_rag.py
│   ā”œā”€ā”€ tool_xmpp.py
│   ā”œā”€ā”€ tool_matrix.py
│   ā”œā”€ā”€ tool_caldav.py
│   ā”œā”€ā”€ tool_memory_encrypted.py
│   ā”œā”€ā”€ tool_image.py
│   └── ...
ā”œā”€ā”€ skills/                       # SKILL.md Mappings
│   └── pdf/
│       ā”œā”€ā”€ SKILL.md
│       └── scripts/
ā”œā”€ā”€ documents/                    # Documents for RAG indexing
│   └── __index__/                # RAG index (do not modify!)
└── memory/                       # Encrypted memory

šŸ”§ Installation

1. Prerequisites

  • Python 3.13

  • Virtual environment (recommended: ctlasistent_mpc/venv)

  • Linux: python3 -m venv venv; source venv/bin/activate

  • Windows: py -m venv venv; venv\Scripts\activate

2. Dependencies

pip install -r requirements
pip install -r requirements-extra

The first run requires internet access to download the embedding model (~90 MB):

HF_HUB_OFFLINE=0 TRANSFORMERS_OFFLINE=0 \
  /ctlasistent_mpc/venv/bin/python -c \
  "from sentence_transformers import SentenceTransformer; \
   SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"

āœ… After this, all calls run offline (HF_HUB_OFFLINE=1 is already set in DocumentIndexer).

4. Automatic Tool Registration

If a tool is not installed, it will not be registered — the server still runs, just without that specific tool.

āš™ļø Configuration

.env — Sensitive Data and Tokens

Create /ctlasistent_mpc/.env:

# XMPP
XMPP_ADDRESS=user@example.com
XMPP_PASSWORD=secret

# Matrix
MATRIX_HOMESERVER=https://matrix.org
MATRIX_USER_ID=@user:matrix.org
MATRIX_PASSWORD=secret
MATRIX_RECOVERY_KEY=...

# CalDAV
CALDAV_BASE=http://127.0.0.1:5232
CALDAV_USER=user_name

# RAG (optional - default is ./documents and ./documents/__index__)
RAG_DOCS_DIR=/path/to/documents
RAG_INDEX_DIR=/path/to/documents/__index__

Secure the file:

chmod 600 /ctlasistent_mpc/.env
echo ".env" >> /ctlasistent_mpc/.gitignore

āš ļø .env is loaded upon server startup (os.environ.setdefault).

tools_server.py — Disabling Tools

python

# ─── DISABLE TOOLS HERE ──────────────────────────────────────
DISABLED = set()               # All tools active
# or selective:
DISABLED = {
    # "rag_index",
    # "rag_status",
    # "rag_search",
    # "ddg_search",
    # "write_file",
    # "cmd",
    # "kdeconnect",
    # "matrix_chat",
    # "xmpp_omemo",
    # "memory",
    # "memory_encrypted",
    # "caldav",
    # "image",
    # "weather",
}

Any tool name in DISABLED will not be registered — the server runs without it.

skills_server.py — Disabling Skill Tools

python

DISABLED = set()               # All skills tools active
# or:
DISABLED = {"list_skills", "read_skill"}

When to disable:

  • llama.cpp (without native skills) → DISABLED = set() — uses our tools

  • DSH, Claude Desktop (have native skills) → DISABLED = {"list_skills", "read_skill"} — prevents duplicates If in doubt, keep it enabled — the model will choose itself.

āœ… Verification Before Connecting

Run the server manually to see if tools are being registered:

bash

cd /ctlasistent_mpc
./venv/bin/python ctrlasistent_mcp.py

Expected output on stderr:

text

āœ… Registered tool: ddg_search
āœ… Registered tool: weather
āœ… Registered tool: rag_search
āœ… Registered tool: rag_index
āœ… Registered tool: rag_status
ā­ļø Skipping: caldav
...

āœ… If you see āš ļø Error loading tool_*.py, the tool has an import problem — see Troubleshooting.

Press Ctrl+C to stop.

šŸ”Œ Connecting to Clients

1. llama.cpp (llama-server)

Two options — choose one.

A) llama.cpp runs the tools (server-side)

The client does not need an MCP config. llama-server runs the MCP server itself and executes the tools internally.

Create llama_mcp.json:

{
  "mcpServers": {
    "ctrlasistent": {
      "command": "/path/to/ctlasistent_mpc/venv/bin/python",
      "args": ["/path/to/ctlasistent_mpcctrlasistent_mcp.py"]
    }
  }
}

āŒ Do not add cwd — if the path doesn't exist, llama-server crashes with ENOENT. The server handles all paths via __file__.

Run:

bash

~/ctlasistent_mpc/llama/llama-server \
  --models-dir ~/ctlasistent_mpc/models/ \
  --port 9931 -ngl 999 -t 4 -np 1 --models-max 1 \
  --ui-mcp-proxy --jinja \
  --cache-type-k q8_0 --cache-type-v q8_0 --flash-attn on \
  --mcp-servers-config /ctrlasistent_mcp/llama_mcp.json

B) Client runs the tools (client-side)

Use this when you want to see tool calls in the client UI or change models without restarting. Run llama-server without --mcp-servers-config, and place the MCP config in the client (OpenCode/Hermes/...).

OpenCode ~/.config/opencode/opencode.json or .opencode.json in the project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ctrlasistent": {
      "type": "local",
      "command": [
        "/ctlasistent_mpc/venv/bin/python",
        "/ctlasistent_mpc/ctrlasistent_mcp.py"
      ],
      "enabled": true
    }
  }
}

Restart OpenCode → /mcp in TUI → ctrlasistent green.

Hermes Agent ~/.hermes/config.yaml:


mcp_servers:
  ctrlasistent:
    command: "/ctlasistent_mpc/venv/bin/python"
    args: ["/ctlasistent_mpc/ctrlasistent_mcp.py"]

Apply without restart: in the active session type /reload-mcp. Check: /tools in the session → tools under mcp__ctrlasistent__*..

DSH Harness cordis.patch.yml or corresponding config:


- insert:
    - id: mcp-ctrlasistent
      name: '@deepseek-ai/dsh-mcp-client'
      disabled: false
      config:
        serverName: ctrlasistent
        transport: stdio
        command: /ctlasistent_mpc/venv/bin/python
        args:
          - /ctlasistent_mpc/ctrlasistent_mcp.py
        failOnStartupError: true 
        startupTimeoutMs: 120000 # give it 2 minutes or more

Claude Desktop ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ctrlasistent": {
      "command": "/ctlasistent_mpc/venv/bin/python",
      "args": ["/ctlasistent_mpc/ctrlasistent_mcp.py"]
    }
  }
}

Restart Claude Desktop → hammer icon in chat.

šŸ“š RAG (Local Knowledge Base)

  • documents/ is recursively scanned (including subfolders).

  • Exclusions: .git, __pycache__, node_modules, .venv, venv, dist, build.

  • Hybrid indexing: FAISS (vector) + BM25 (keyword).

  • Reindexing only changed files (SHA-256 hash).

Tools

Tool

Description

rag_search(query, k=3)

Searches the index, returns excerpts with [Source File: ...]

rag_index()

Starts reindexing in the background (returns immediately)

rag_status()

Returns idle / running / done / failed

āœ… Place files in documents/ (anywhere inside). The first rag_search automatically indexes everything.

Reindexing

To add new files on the fly:

rag_index → rag_status  # until 'done' is visible
# or restart the server — automatically indexes everything new

šŸŽÆ Skills

Skill.md Format

---
name: pdf
description: PDF manipulation toolkit. Use when the user wants to create, edit, merge, split, or extract from PDF files.
---

# PDF Skill

## Instructions

...

## Scripts

Scripts are in `scripts/` relative to this SKILL.md.

How the Model Uses It

  1. First step → list_skills() → sees the list.

  2. Second step → read_skill("pdf") → gets content with ENVIRONMENT header:

## ENVIRONMENT
- OS: Linux ...
- Python interpreter: ./venv/bin/python
- Skill directory: /ctlasistent_mpc/skills/pdf
...

āœ… The model knows where the scripts are and which interpreter to use.

SkillsDirectoryProvider (native clients)

For clients with native skills support (Claude Desktop, newer OpenCode), skills_server.py exposes skill:// resources via SkillsDirectoryProvider. No configuration needed — they register automatically.

āž• Adding a New Tool

Create tools/my_tool.py:

python

from typing import Any, Dict
from core.CtrlAsistent_tools import Tool


class MyTool(Tool):
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return (
            "When to use this tool. 'Use THIS when...' \n"
        )
 
    @property
    def parameters_schema(self) -> Dict[str, Any]:
        return {
            "query": {
                "type": "string",
                "description": "What the tool accepts",
            },
        }

    def execute(self, query: str) -> str:
        return f"Result for: {query}"

Rules:

  • The class must inherit from Tool (it does not need __init__.py in tools/).

  • name must be unique (check for collisions with other MCP servers).

  • description must state when to use it, not just what it does.

  • execute can have type hints (used for schema) or a parameters_schema property.

  • For images, return fastmcp.utilities.types.Image (not a base64 string).

  • For asynchronous calls, use the _run_safely wrapper (see tool_xmpp.py).

  • Restart the client → the tool is automatically registered. No changes to tools_server.py or ctrlasistent_mcp.py are needed.

šŸ› Troubleshooting

Server runs, but tools are not visible in the client

  1. Check manually (as above): python ctrlasistent_mcp.py → do you see āœ… Registered tool: ...?

    • No → import problem in the tool, see next step.

    • Yes → problem is in client config.

Client does not start the server

ps aux | grep ctrlasistent_mcp
  • If no processes → config is incorrect.

  • If processes exist → problem is in client registration.

spawn ... ENOENT (Node.js clients: OpenCode, DSH)

99% of the time: cwd in the config points to a non-existent directory. Fix: Remove cwd from the config.

KeyError: 'tool_xmpp' or similar

Cause: the tool uses sys.modules[__name__] but the loader didn't register it. Fix: already in tools_server.py (sys.modules[py_file.stem] = module before exec_module).

āš ļø Cannot instantiate X: ...

The tool cannot be instantiated. Causes:

  • Constructor requires arguments (e.g., def __init__(self, api_key)) — add default or load from .env.

  • Package is missing in execute or __init__ — pip install <package>.

āš ļø Error loading tool_X.py: ...

Module crashes on import. Most common:

  • Missing package → pip install.

  • Syntax error → python -c "import tools.tool_X" for details.

  • KeyError / TypeError: unexpected keyword argument.

    • The client (or AI) sent a parameter the tool doesn't accept (e.g., cwd).

    • Resolved in safe_fn — unrecognized parameters are silently discarded with a log:

    text
    
    āš ļø weather: dropped unknown kwargs: ['cwd']

    If you see this line, the tool is working correctly. If not, check that the filter is active in register_tool.

rag_index timeout in client

Client has a 60s timeout, but reindexing takes longer. Solution: background reindex (already implemented). rag_index returns ā³ started immediately. rag_status shows progress: starting / indexing / done / failed. The first run includes embedding model loading (~15-30s).

RAG not finding files

  • Are they in documents/? Check: find documents/ -type f | head

  • Are supported extensions used? See the list above.

  • Are they in a skipped folder? node_modules, .git, dist, build are skipped.

  • Check the log: Found N candidate files in ... and the list below.

    • If N=0: run rag_index and check the stderr logs.

Model hallucinates parameters

The AI adds parameters that the tool doesn't accept (cwd, context, path). Resolved in safe_fn — the filter discards extras. In the log, you can see what was discarded. If it persists, improve the tool's description to explicitly state what it accepts:

"Accept ONLY the 'city' parameter (string). Does not accept paths or cwd."

faiss.loader: Could not load library with AVX512 support

Cosmetic message — FAISS quietly falls back to generic build. It does not affect functionality. To suppress:

import logging
logging.getLogger("faiss.loader").setLevel(logging.WARNING)

Model loads slowly (starting takes too long)

Run rag_setup.py — shows exactly where it is hanging:

cd /ctlasistent_mpc;
/ctlasistent_mpc/venv/bin/python rag_setup.py

You will see: cache model, loading, scanning, counting files, indexing.

Hermes/OpenCode do not see tools even though they work manually

  1. Check /mcp in the client.

  2. Check that the config uses the correct format:

    • OpenCode: mcp

    • Hermes: mcp_servers

    • Claude: mcpServers

  3. Check that there is no cwd with a non-existent path.

  4. Restart the client (not just /reload-mcp) — the tool list changes.

šŸ”’ Security

  • **.env** contains passwords — chmod 600, do not commit.

  • memory/ is encrypted with Fernet (or XOR fallback if cryptography is not installed).

  • __index__/ contains your original documents in chunks — do not share if sensitive.

  • The MCP server has access to the file system.

šŸ“Œ Note

Documentation is subject to updates — check that it is compatible with the server version you are using.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables local RAG orchestration with MCP, providing context retrieval, in-memory text ingestion, explicit tool invocation, and transport-neutral tool discovery.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to discover and create agents, durably submit messages with verifiable replies, and search source-linked local memory. Exposes eight authenticated tools with owner-approved OAuth, transcript-backed verification, and explicit control over history import and embedding.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI assistant to invoke local file operations, multi-engine web search, weather, system commands, developer utilities, and code execution over MCP, and includes a web dashboard for managing endpoints, testing tools, and viewing live logs.
      65 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-compatible applications to manage and use local or cloud-hosted models, including listing, pulling, generating, chatting, embeddings, and web search/fetch through a unified tool interface.
      817 npm
      AGPL 3.0