m-indsRefuge/hermes-agent

Hermes-Agent (MCP Server - V1, Python + FastAPI)

Overview

Hermes-Agent is a lightweight, secure MCP (Model Control Protocol) server that allows controlled local OS interaction via ChatGPT.
It is designed for security-first, read-only, memory-efficient operation on constrained systems (≈4 GB RAM, no Docker).

• ⚡ Python + FastAPI backend
• 🔒 Scoped, read-only FS access (allowlist)
• 🧩 Pluggable auth and security layers
• 🪟 Windows-native deployment (NSSM or sc.exe)
• 🛡️ Upgrade path to Go/Rust for hardened single-binary

Setup Guide

1. Clone the repository

powershell git clone https://github.com/your-username/hermes-agent.git cd hermes-agent

2. Create and activate virtual environment

python -m venv .venv
.\.venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

Copy the example environment file:

cp config\settings.example.env config\.env

(On Windows PowerShell, you may also use: Copy-Item config\settings.example.env config\.env)

Then edit config\.env to match your system paths, tokens, and preferences:

• ALLOWED_PATHS → must include the SysLearn repo root (or other safe allowlist paths).
• SOCKET_PATH → adjust for Windows (\\.\pipe\hermes-agent) or Unix domain sockets.
• LOG_LEVEL → set to DEBUG for development, INFO or WARN for production.
• TOKEN_TTL_SECONDS → controls ephemeral token lifetime.

5. Run in development

.\scripts\run-dev.ps1

This starts Hermes-Agent via Uvicorn bound to a Windows named pipe (\\.\pipe\hermes-agent).

6. Install as a Windows service (optional)

Using sc.exe:

.\scripts\install-service.ps1

Or, if you have NSSM:

.\scripts\install-nssm.ps1

Folder Structure

hermes-agent/ │ ├── src/hermes/ # Core server source │ ├── api/ # API routes │ ├── auth/ # Authentication + tokens │ ├── security/ # Security filters & policies │ └── utils/ # Helper modules (safe I/O, etc.) │ ├── config/ # Environment configs │ ├── settings.example.env │ └── .env (local only, not committed) │ ├── scripts/ # Run/install scripts ├── tests/ # Unit & integration tests ├── docs/ # Documentation ├── logs/ # Runtime logs ├── requirements.txt └── README.md

Security Defaults

• ✅ Filesystem access restricted to allowlisted paths
• ✅ Strict path canonicalization (no traversal)
• ✅ Ephemeral scoped tokens
• ✅ Enforced file size limits
• ✅ No execution or write capabilities in V1

⚠️ Important:

• Never commit config/.env to version control.
• Only config/settings.example.env should be tracked and shared.
• Each developer should create their own .env by copying the example.

Do you want me to also patch your .gitignore so it’s guaranteed that config/.env is never committed, even by accident?