Skip to main content
Glama
HoAnTrieu

sovereign-exoself-mcp

by HoAnTrieu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

sovereign-exoself-mcp

Local MCP server for personal AI Council. Routes tasks through manager, worker, critic, synthesizer, and archivist with fast/review/full paths. Uses SQLite memory with WAL and FTS5. Supports mock, Ollama, and OpenRouter providers.

Architecture

flowchart LR
  C[MCP stdio client] --> T[3 tools]
  T --> O[Council Router]
  O --> M[Manager<br/>granite3.3:2b]
  M -->|fast| W[Worker<br/>qwen2.5-coder:7b]
  M -->|review| W
  M -->|full| W
  W -->|review| CR[Critic<br/>qwen2.5-coder:7b]
  CR -->|reject| W
  CR -->|approve| S[Synthesizer<br/>granite3.3:2b]
  S -->|full| A[Archivist<br/>granite3.3:2b]
  S --> R[Result]
  A --> R

Related MCP server: orchestrator-mcp

Model Configuration (Config B)

Role

Model

Rationale

Manager

granite3.3:2b

Fast routing decisions

Worker

qwen2.5-coder:7b

Quality code execution

Critic

qwen2.5-coder:7b

Reliable code review

Synthesizer

granite3.3:2b

Fast result merging

Archivist

granite3.3:2b

Fast memory extraction

Benchmark: 1504ms avg, 3428ms P95, 100% success rate, 0 timeouts.

Quick Start

Requirements: Ubuntu/Linux, Python 3.14, uv.

cd /home/hat/AionUI/sovereign-exoself-mcp
bash scripts/install.sh
bash scripts/smoke_test.sh --mock

--mock mode requires no API key and is useful for offline validation. For real inference, run the server directly with a provider (see below). scripts/generate_client_configs.py auto-generates host snippets (dist/) that enable a real provider: ollama by default, openrouter when OPENROUTER_API_KEY is present.

Ollama Mode

# Pull required models
ollama pull granite3.3:2b
ollama pull qwen2.5-coder:7b

# Run with Ollama
SOVEREIGN_PROVIDER_MODE=ollama \
uv run python -m sovereign_exoself_mcp

OpenRouter Mode

# Secrets are environment-only: store the key in the gitignored `.env` file
echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env

SOVEREIGN_PROVIDER_MODE=openrouter \
uv run python -m sovereign_exoself_mcp

Council Routes

Fast Path (Default)

Manager → Worker → Result. Used for simple questions, facts, quick analysis.

Review Path

Manager → Worker → Critic → Synthesizer → Result. Used for code changes, architecture decisions.

Full Council

Manager → Worker → Critic → Synthesizer → Archivist → Result. Used for complex tasks requiring memory.

API Tools

council_run

{
  "task": "Review and improve the configuration loader.",
  "mode": "auto",
  "budget": "low",
  "worker_profile": null,
  "needs_memory": null,
  "max_rounds": null,
  "route_override": null
}

Mode values: auto (manager decides), code, analysis, decision. As a shorthand, mode also accepts fast, review, or full to force a route directly. An explicit route_override (fast/review/full) always wins when provided.

Response includes: run_id, status, route, models, result, metrics, memory_updates, warnings

memory_manage

{
  "action": "search",
  "query": "design decisions"
}

Actions: search, store, list, delete, export, profile

system_status

Returns health, provider mode, model mapping, prompt versions, active runs, Ollama status.

Changing Models

# Environment variables
export SOVEREIGN_OLLAMA_WORKER_MODEL=qwen3:8b
export SOVEREIGN_OLLAMA_MANAGER_MODEL=gemma2:2b

# Or config file
cp config/council.example.yaml config/council.yaml
# Edit config/council.yaml

Worker Profiles

Profile

Purpose

code_engineer

Code implementation, debugging, refactoring

system_engineer

Infrastructure, DevOps, system design

researcher

Information gathering, analysis

technical_writer

Documentation, prose

planner

Task decomposition, project planning

general_operator

Default fallback

Running Benchmark

# Mock benchmark
python benchmarks/benchmark.py --mode mock

# Live benchmark (requires Ollama with models)
OLLAMA_TEST_MODEL=qwen2.5-coder:7b python benchmarks/benchmark.py --mode ollama

System Status

# Via MCP tool
system_status({})

# Via CLI
uv run python -c "import asyncio; from sovereign_exoself_mcp.providers import probe_ollama; print(asyncio.run(probe_ollama('http://127.0.0.1:11434', 5)))"

Rollback

  1. Set SOVEREIGN_PROVIDER_MODE=mock

  2. Remove new environment variables

  3. Revert code changes

Adding Worker Profiles

  1. Create src/sovereign_exoself_mcp/prompts/profiles/<name>.txt

  2. Add to PROFILES list in prompts.py

  3. Use in requests: {"worker_profile": "<name>"}

Environment Variables

See .env.example for all available settings.

Documentation

Testing

# Run all tests
python -m pytest tests/ -v

# Run specific test suite
python -m pytest tests/unit/test_prompts.py -v
python -m pytest tests/unit/test_router.py -v
python -m pytest tests/unit/test_schemas.py -v

License

MIT

Available Tools

3 tools
council_runD

Run the bounded personal council.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoauto
taskYes
budgetNolow
max_roundsNo
session_idNo
needs_memoryNo
output_formatNotext
route_overrideNo
worker_profileNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It only says 'Run the bounded personal council' without mentioning side effects, permissions, state changes, or expected outcomes, leaving the agent blind to the tool's runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, but it is under-specified rather than concisely informative. It contains no meaningful detail and does not earn its brevity, as it offers no value beyond restating the tool's name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 9 parameters and an output schema, but the description provides no information about return values, invocation context, or expected behavior. This is highly inadequate for a tool of this complexity, especially given the absence of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning all 9 parameters are undocumented in the schema. The description adds no parameter information, failing to compensate for the complete lack of meaning around task, mode, budget, max_rounds, and other parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses 'Run' as a verb and 'the bounded personal council' as a resource, giving a clear syntactic structure. However, the phrase is vague and does not explain what the council is, what 'run' entails, or how it differs from sibling tools like memory_manage and system_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use council_run versus the sibling tools, nor does it mention any alternative approaches or exclusions. It simply states the action without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_manageB

Search, store, list, delete, export, or profile memory.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNo
limitNo
queryNo
actionYes
contentNo
memory_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies mutation (store, delete) but does not disclose side effects, reversibility, permission requirements, or output format. The mention of 'delete' hints at destructive behavior, but without details the agent cannot anticipate consequences.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the tool's core actions. Every word contributes value, with no fluff or repetition. It is optimally concise for the high-level purpose it conveys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 6 parameters and multiple actions, the description gives no information about which parameters are required for each action, what the output looks like, or any operational constraints. The output schema exists but its content is not shown, and the description does not compensate. For a tool with this complexity, the description is insufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description's list of verbs ('search', 'store', 'list', 'delete', 'export', 'profile') effectively documents the possible values for the required 'action' parameter. However, other parameters (kind, limit, query, content, memory_id) are left unexplained, so the description only partially compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with specific verbs (search, store, list, delete, export, profile) on the resource 'memory'. This distinguishes it from sibling tools like council_run and system_status, which are unrelated operations. The verb list is concrete and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists possible actions but provides no guidance on when to use this tool versus alternatives, nor when to choose one action over another. It does not mention prerequisites, exclusions, or context like whether memory management is preferred over other tools for specific tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

system_statusA

Return local health without calling a provider.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait—that it does not call a provider—which indicates it is local and likely non-blocking. However, it does not specify side effects (e.g., whether it checks resource usage, connectivity, etc.) or any other behavioral details beyond the basic request.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, streamlined sentence that conveys the essential purpose in a few words. Every word earns its place, and there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple zero-parameter health check tool with an output schema present. The description, combined with the output schema, provides sufficient context for an agent to understand what the tool does and what it returns. No additional details are necessary for this complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema coverage is trivially 100% (no properties). The description does not need to explain parameters, and the baseline for 0 params is 4. It adds no parameter info, which is fine here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Return' and identifies the resource as 'local health', clearly distinguishing it from sibling tools like council_run and memory_manage. The phrase 'without calling a provider' adds scope and context, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool ('when you want local health without calling a provider') but does not explicitly state when not to use it or provide comparisons to sibling tools. It gives a clear context clue but lacks explicit alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedcouncil_run
    • First observedmemory_manage
    • First observedsystem_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct domain: running a council, managing memory, and checking system status. There is no overlap in functionality, so an agent can easily select the right tool.

Naming Consistency4/5

Tools use a consistent underscore-separated, lowercase pattern. The first two are noun-verb compounds (council_run, memory_manage), while system_status is a noun-noun compound, creating a minor inconsistency, but it's still readable and recognizable.

Tool Count5/5

With only three tools, the server is tightly focused on the core functions of a personal exoself: decision-making (council), memory, and health. The count is small but each tool has a clear purpose and fits within the typical well-scoped range.

Completeness4/5

The memory_manage tool covers a full range of memory operations, and council_run covers the main action for the council. A possible gap is the lack of configuration or lifecycle management for the council, but for a bounded personal council, this may be sufficient, so the core workflows are covered.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers