# hermes-mcp-s

hermes-mcp-s is a modular MCP suite host for Hermes and other agents. It provides one stdio MCP server that can load long-lived personal automation capabilities as installable external modules.

This project implements the host framework. The main project does not include RSS Radar, Telegram, WeChat, GitHub star, Notion, Feishu, or other business modules.

## Scope

Core is responsible for the MCP server host, explicit module loading, tool registration, configuration, runtime context, module status reporting, policy flags, logging, and a minimal SQLite storage foundation.

External modules own their domain logic, tool names, validation, and any integrations. Module tools should use their own domain prefixes, such as `rss_*`, `notion_wiki_*`, or `server_*`. Built-in host tools use `system_*`.

The current host supports stdio MCP only. HTTP and StreamableHTTP are out of scope.

External side effects are disabled by default through `policy.external_side_effects: false`.

Module authors should read [docs/module-authoring.md](docs/module-authoring.md). Current configuration fields are documented in [docs/config-schema.md](docs/config-schema.md).

The repository includes a minimal external module example in `examples/hello_module/`. It can be loaded with the config shape shown in `examples/hello_config.yaml` when the example package is on `PYTHONPATH`. The example stores local runtime state under `tmp/`, which is ignored by git.

## Development

Install development dependencies:

```bash
python -m pip install -e .[dev]
```

Run tests:

```bash
python -m pytest
```

List tools:

```bash
hermes-mcp-s list-tools --config config.example.yaml
```

Show module status:

```bash
hermes-mcp-s module-status --config config.example.yaml
```

Start the stdio MCP server:

```bash
hermes-mcp-s serve --config config.example.yaml
```

## Hermes MCP Configuration

Add an MCP server entry like this to the Hermes config.yaml. Replace the config path with your local path.

    mcp_servers:
      hermes_mcp_s:
        command: "hermes-mcp-s"
        args: ["serve", "--config", "path/to/config.yaml"]

## Secrets

Secrets must live in `.env` or environment variables, not in configuration files, examples, tests, or repository notes. Configuration may reference only environment variable names such as `HERMES_MCPS_MODEL_API_KEY` or `GITHUB_TOKEN`.

By default, hermes-mcp-s loads an `.env` file beside the selected config file when it exists. You can also pass `--env-file path/to/.env`.