Metadata-Version: 2.5
Name: feagi-mcp
Version: 0.0.20
Summary: MCP server for FEAGI neural monitoring and control
Project-URL: Homepage, https://github.com/Neuraville/feagi-mcp
Project-URL: Repository, https://github.com/Neuraville/feagi-mcp
Project-URL: Issues, https://github.com/Neuraville/feagi-mcp/issues
Project-URL: Documentation, https://feagi.org
Author-email: "Neuraville Inc." <feagi@neuraville.com>
License: Apache-2.0
License-File: LICENSE
Keywords: brain,feagi,mcp,monitoring,neural,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: feagi-core==2.2.4
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff==0.16.10; extra == 'dev'
Description-Content-Type: text/markdown

# FEAGI MCP Server

Model Context Protocol (MCP) server for FEAGI neural monitoring and control. Enables LLMs to observe brain activity, design neural circuits, and debug neurorobotic systems in real-time.

## Features

### Monitoring & Observation
- **Monitor cortical activity** - Real-time firing rates, spike patterns, and neuron states
- **Trace signal paths** - Verify connectivity between cortical areas
- **Inspect embodiment** - Check controller registration, motor/sensor mappings
- **Analyze connectivity** - Examine synaptic connections and morphologies

### Circuit Building
- **Stimulate areas** - Trigger specific cortical regions for testing
- **Validate circuits** - Check genome structure and parameter sanity
- **Get area parameters** - Inspect neuron properties and dimensions

### Genome Management
- **Upload genomes** - Load neural architectures into running FEAGI
- **Download genomes** - Retrieve current brain configuration
- **List areas** - Enumerate all cortical regions

External `.genome` files pass through `feagi_mcp.genome_artifact`. The current
codec uses UTF-8 JSON, but artifact encoding is separate from the embedded
`genome_schema_version` and its FEAGI migration chain. Direct JSON parameters
to MCP tools remain API documents rather than file artifacts. MCP snapshots
store the standard genome artifact in `<label>.genome` and keep snapshot-only
annotations in `<label>.snapshot.json`.

### Composer integration (optional)
- **Simulator asset packs** - List/resolve/download shared packs from Composer when `FEAGI_COMPOSER_BASE_URL` is set

## Installation

```bash
# From PyPI
pip install feagi-mcp

# Or install from a source checkout (editable)
cd feagi-mcp
pip install -e .

# Or with uv
uv pip install -e .
```

## Usage

### Standalone Server (stdio)

```bash
feagi-mcp
```

### With Configuration

```bash
export FEAGI_HOST=localhost
export FEAGI_PORT=8000
# Optional: Composer public API (shared simulator packs, embodiment metadata APIs, etc.)
export FEAGI_COMPOSER_BASE_URL=https://staging-api.brainsforrobots.com
feagi-mcp
```

### Cursor Integration

Add to your Cursor MCP settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "feagi": {
      "command": "python",
      "args": ["-m", "feagi_mcp.server"],
      "env": {
        "FEAGI_HOST": "localhost",
        "FEAGI_PORT": "8000",
        "FEAGI_COMPOSER_BASE_URL": "https://staging-api.brainsforrobots.com"
      }
    }
  }
}
```

## Available Tools

### Agent Introspection
- `get_registered_agents` - List registered agents with ids and `agent_name`
- `get_agent_properties` - Get agent type, capabilities, version, connection info
- `get_agent_device_registrations` - Inspect motor/sensor structure, group_ids, control modes. Prefer `get_motor_group_summary` / `explain_cortical_area_naming` for musculoskeletal agents.
- `compare_device_registration_store` - Compact session vs descriptor registration keys (`poll_source`, leftover `SegmentedVision`)
- `get_motor_group_summary` - Compact motor bundle titles, unit ids, and channel counts
- `explain_cortical_area_naming` - Why a live area has its title (e.g. `ungrouped-1`)

### Monitoring
- `monitor_activity` / `monitor_activity_batch` - Firing rates and lifetime stats. `summary_only=True` (default) omits `spike_history` and neuron-id lists.
- `get_connectivity` - Inspect synaptic connections between areas
- `trace_signal_path` - Verify signal propagation paths
- `get_embodiment_status` - Live controller registry + compact I/O catalog (`/v1/embodiment/status` when present)
- `get_sensor_snapshot_last` - Latest sensor tap. Default `summary_only` returns per-Z stats, not every voxel.
- `get_area_parameters` - Inspect neuron properties
- `get_cortical_synapse_counts` - Incoming/outgoing synapse counts from `cortical_area_properties` (running counters; can drift after a resize)
- `get_log_tail` - FEAGI process logs. Pass `message_contains` instead of dumping the ring buffer. Requires HTTP.
- `get_last_failed_mutation` - Most recent failed mutating API call (method/path/status/content-length/error). Use when health is fine but upload/load failed.
- `diagnose_feagi_runtime` - Local-first stall diagnosis (`feagi-core.log`, desktop log, `FEAGI_LOG_FILE`, then HTTP ring). Also attaches `last_failed_mutation` when HTTP answers. Returns `paths_checked`. Use when `health_check` times out or FEAGI has exited.

### Genome Editing (NEW)
- `create_brain_region` - Create the named circuit container. Title must name the function (Sit, Walk CPG); Autogen Circuit / Untitled are rejected.
- `create_cortical_area` - Add OPU/IPU/CUSTOM/MEMORY areas programmatically (CUSTOM/MEMORY require a function-named `brain_region_id`; MCP enforces origin/label spacing unless skipped). **Naming:** circuit title = function; area names = role; never prefix with `Mcp` — see `docs/NEW_TOOLS.md` (Circuit naming policy).
- `update_cortical_area` - Modify cortical area properties
- `set_memory_mp_encoding` - Set a memory area's MP encoding (`none`, `mp_learning`, `mp_differential`, `mp_ratio`) plus its quantization in one call; validates locally and returns the effective mode (warns when FEAGI auto-disables a change mode for temporal_depth < 2)
- `delete_cortical_area` - Remove cortical areas
- `list_opu_areas` - List only motor output areas
- `list_ipu_areas` - List only sensory input areas
- `list_io_areas_compact` - Compact IPU/OPU inventory (subtype, dimensions, `dev_count`, dimension mismatch). Prefer this over `*_with_metadata`.
- `list_opu_areas_with_metadata` - List OPU areas with semantic type/purpose/capabilities info
- `list_ipu_areas_with_metadata` - List IPU areas with semantic type/purpose/capabilities info (do not use for encoder inventories)
- `get_area_semantic_info` - Get detailed semantic information about any cortical area

### Connection Management (NEW)
- `propose_connectivity_rule` - Local compact-rule judgment (`*` / `?` / `?+N`). Call before `create_morphology`.
- `get_morphology` - Fetch one morphology. Compact rules include parameters by default; enumerated dumps omit them unless requested (`judgment.compact_form` when rows should be `N..M`). Prefer this over `list_morphologies`.
- `update_morphology` - Replace an existing morphology and rebuild mappings that use it. Same compactness gate as `create_morphology`.
- `get_cortical_mapping` - Get connection configuration between two areas
- `validate_magnitude_passthrough` - One-call check that graded IPU magnitudes (audio spectrum, analog sensors) reach an OPU unchanged: `mp_driven_psp`, threshold gating, scaling, fan-out, dimensions, and a realized-wiring sample at the far edge voxel. Each finding carries an `update_cortical_area` fix when one applies. Pass `class_count` for class maps: any drift becomes an error.
- `wire_value_passthrough` - Wire a one-layer value plane (classifier twin, Depth Map) 1:1 so each potential arrives exactly (source forwarding, destination threshold/leak/accumulation, projector mapping), then validate.
- `expand_value_to_bins` - Build a `W x H x levels` bin area from a value plane with a Z threshold ramp (cumulative code), for depth ranges or one neuron per class.
- `decode_class_map` - Decode the last burst of a class map (`(class_id + 1) / class_count`) into a class histogram and capped pixel rows from one fire-queue read.
- `create_classifier` / `update_classifier` / `attach_classifier_field` - Create and edit classifier assemblies (scanner mode takes `class_count`) and bind image fields (each gets a `W x H x 1` twin).
- `measure_audio_io_disparity` - While audio is streaming, compare each input frequency column with the output column it produced. Reports which gap dominates: dropped frames, dropped columns, phase, or magnitude.
- `update_cortical_mapping` - Create/update connections with morphology rules
- `delete_cortical_mapping` - Remove connections between areas

### Composer shared simulator packs (optional)
Set `FEAGI_COMPOSER_BASE_URL` to the Composer HTTPS root (e.g. staging). Read-only routes under `/v1/public/global/simulator-packs`.
- `composer_list_simulator_packs` - Catalog with optional filters (`engine`, `kind`, `state`)
- `composer_get_simulator_pack_versions` - Version index for a `pack_id`
- `composer_get_simulator_pack_resolved` - Resolved manifest and per-file HTTPS URLs (GCS)
- `composer_download_simulator_pack_bundle` - Fetch every listed file into a local directory for MJCF `include` wiring (MuJoCo still requires XML edit + model reload)

### Brain Visualizer parity (full REST router)
- `list_brain_visualizer_operations` - Index of every supported `operation_id` with HTTP method and path (same surface as `FEAGIHTTPAddressList.gd`)
- `brain_visualizer_api` - Call any whitelisted operation: genome (save, amalgamation, circuits), cortical areas (geometry, properties, multi-put, reset, clone), regions (CRUD, relocate, clone), morphologies (CRUD, rename, usage), cortical mappings (afferents, efferents, batch), burst engine, system visualization tuning, neuroplasticity, insight/monitoring, agents (register, heartbeat, stimulation, device registrations), network, vision input. Use `path_params` for `{agent_id}` / `{region_id}` routes; for amalgamation-by-upload use `post_genome_amalgamation_by_upload_multipart` with `json_body: {\"genome_json\": \"...\"}`.
- **Voxel / neuron inspection:** For a specific cortical area and voxel `(x,y,z)`—neuron details, incoming/outgoing synapses at that voxel, or debugging—use `operation_id` **`get_cortical_area_voxel_neurons`** (GET `/v1/cortical_area/voxel_neurons`) with `query`: `cortical_id`, `x`, `y`, `z`, optional `synapse_page`.

### Control
- `stimulate_area` - Trigger neurons for testing
- `upload_genome` - Load a new brain architecture
- `download_genome` - Retrieve current genome

### Inspection
- `list_cortical_areas` - List areas; filter by name, id, or type to avoid a full-genome dump
- `list_memory_neurons` - List paginated runtime memory-neuron IDs and ST/LT counts
- `inspect_memory_neuron` - Inspect one memory neuron's lifecycle and weighted synaptic edges
- `diagnose_mapping_plasticity` - Inspect plastic rules and realized source-to-destination weights
- `get_genome_info` - Get metadata about current genome
- `validate_genome` - Check genome structure for issues
- `get_burst_engine_status` - Check burst engine state
- `get_runtime_metrics` - Get comprehensive runtime metrics

## Example: LLM-Assisted Circuit Design

```python
# LLM can now:
# 1. Monitor CPG oscillation
activity = await monitor_activity(area_id="cCPGa_", duration_ms=1000)
# Returns: {"firing_rate": 5.2, "active_neurons": [0,1,2,3,4], "period_ms": 192}

# 2. Verify connections
conn = await get_connectivity(src_area="cCPGa_", dst_area="cHipFL")
# Returns: {"synapse_count": 150, "morphology": "cpg_to_hip_x", "avg_weight": 18.0}

# 3. Check motor output
status = await get_embodiment_status()
# Returns: {"motor_cortical_id": "opose0", "device_count": 12, "last_packet_ms": 42}

# 4. Debug with stimulation
result = await stimulate_area(area_id="cStart", coords=[0, 0, 0], potential=1.0)
# Trigger walking behavior for testing
```

## Architecture

```
feagi-mcp/
├── src/feagi_mcp/
│   ├── __init__.py
│   ├── server.py          # Main MCP server with tool definitions
│   ├── feagi_client.py    # HTTP client for FEAGI REST API
│   ├── config.py          # Configuration management
│   └── tools/             # Individual tool implementations
│       ├── monitoring.py
│       ├── control.py
│       └── genome.py
├── tests/
│   ├── test_server.py
│   └── test_feagi_client.py
├── examples/
│   └── circuit_design.py
├── pyproject.toml
└── README.md
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check .
ruff format .
mypy src/
```

## Requirements

- Python 3.10+
- Running FEAGI instance (default: localhost:8000)
- MCP-compatible client (Cursor, Claude Desktop)

## License

Apache-2.0 - Copyright 2026 Neuraville Inc.

## Support

- Issues: https://github.com/Neuraville/feagi-mcp/issues
- Discord: https://discord.gg/PTVC8fyGN8
