CtrlAsistent MCP Server
OfficialProvides an optional KDE Connect tool (kdeconnect) for interacting with KDE Connect devices/services.
Provides Matrix chat integration using configured homeserver credentials, exposing a matrix_chat tool for interacting with Matrix.
Provides XMPP messaging integration using configured XMPP account credentials, including an xmpp_omemo tool for encrypted chat.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
š 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/activateWindows:
py -m venv venv; venv\Scripts\activate
2. Dependencies
pip install -r requirements
pip install -r requirements-extraThe 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 toolsDSH,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.pyExpected 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.jsonB) 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 moreClaude 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 |
| Searches the index, returns excerpts with [Source File: ...] |
| Starts reindexing in the background (returns immediately) |
| Returns |
ā
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
First step ā
list_skills()ā sees the list.Second step ā
read_skill("pdf")ā gets content withENVIRONMENTheader:
## 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__.pyintools/).namemust be unique (check for collisions with other MCP servers).descriptionmust state when to use it, not just what it does.executecan have type hints (used for schema) or aparameters_schemaproperty.For images, return
fastmcp.utilities.types.Image(not a base64 string).For asynchronous calls, use the
_run_safelywrapper (seetool_xmpp.py).Restart the client ā the tool is automatically registered. No changes to
tools_server.pyorctrlasistent_mcp.pyare needed.
š Troubleshooting
Server runs, but tools are not visible in the client
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_mcpIf 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
executeor__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 | headAre supported extensions used? See the list above.
Are they in a skipped folder?
node_modules,.git,dist,buildare skipped.Check the log:
Found N candidate files in ...and the list below.If N=0: run
rag_indexand 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.pyYou will see: cache model, loading, scanning, counting files, indexing.
Hermes/OpenCode do not see tools even though they work manually
Check
/mcpin the client.Check that the config uses the correct format:
OpenCode:
mcpHermes:
mcp_serversClaude:
mcpServers
Check that there is no
cwdwith a non-existent path.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 ifcryptographyis 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ā¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server ā exposes tasks, projects, messages, and files as tools for AI agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables local RAG orchestration with MCP, providing context retrieval, in-memory text ingestion, explicit tool invocation, and transport-neutral tool discovery.-
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmAGPL 3.0