Skip to content
Back to search

agent-mcp

Declare every MCP server once and install it into Claude Code, Codex, OpenCode and Pi on macOS, Arch and Debian.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fnayou--agent-mcp/badge.svg)](/listings/fnayou--agent-mcp)

HTML

<a href="/listings/fnayou--agent-mcp"><img src="/api/listings/fnayou--agent-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`scripts/installer.py` registers every server of `servers.yaml` into each harness found on PATH: Claude Code, Codex, OpenCode and Pi. It validates the manifest first and stops on any error.

| Command | Effect | |---|---| | `task install` | Check `requires`, then register every applicable server. | | `task sync` | Install, update changed servers, and remove recorded servers the manifest no longer names. A second run changes nothing. | | `task uninstall` | Remove the recorded entries, then clear the state. | | `task doctor` | Also reports whether each installed harness has each server, reading config files only. |

Add `-- --dry-run` to `install` or `sync` (`task install -- --dry-run`) to print the plan per harness and write nothing, not even the state file or backups. Each line is `add`, `update`, `replace`, `remove`, `unchanged` or `skip`.

- A server is skipped, with the reason, when its `os` or `harnesses` exclude this machine or harness. A harness whose binary is not on PATH is skipped too. - A server with a missing `requires` dependency is skipped with `MISSING: <dependency>` and its hint. The other servers continue and the exit status is non-zero. - Claude Code and Pi are written with their own commands. Codex (`~/.codex/config.toml`) and OpenCode (`~/.config/opencode/opencode.jsonc`) are edited in place; the Codex edit keeps other tables and comments. OpenCode stops with a message if the file has comments, which an edit would drop. - **State file:** `${XDG_STATE_HOME:-~/.local/state}/agent-mcp/state.json` records, per harness, the names this repo installed and a hash of each entry. - **Backups:** before editing a file directly, the installer copies it to `<state dir>/backups/<harness>-<UTC timestamp>.<ext>`. Backups never go next to the config file. - **Replace policy:** an entry with the same name that the state file does not record is removed and registered again from the manifest, then recorded. The plan shows it as `replace`. - `uninstall` touches only recorded entries. An entry the manifest does not name, such as one added by hand, is never changed.

`task test` runs the installer tests. They use temporary directories and never start a harness command.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 142 lines
  1. # fnayou/agent-mcp
  2. Declare every MCP server once and install it into Claude Code, Codex, OpenCode and Pi on macOS, Arch and Debian.
  3. ## Getting started
  4. Follow the [operator guide](docs/operator-guide.md): prerequisites, one-time setup per machine, install, day-to-day commands and undo.
  5. ## Server manifest
  6. `servers.yaml` declares every MCP server and the dependencies it needs. `servers.schema.json` defines the format; `task manifest:check` validates the manifest, and `task doctor` runs the same check.
  7. ```yaml
  8. schema_version: 1
  9. requires:
  10. agent-browser:
  11. check:
  12. path: ${HOME}/.agents/skills/agent-browser/scripts/agent-browser-mcp
  13. hint: Install the agent-browser skill from https://github.com/fnayou/agent-skills
  14. servers:
  15. playwright:
  16. description: Agent-only headless browser with an in-memory profile, for general web work
  17. transport: stdio
  18. command: ${HOME}/.agents/skills/agent-browser/scripts/agent-browser-mcp
  19. startup_timeout_sec: 30
  20. requires: [agent-browser]
  21. codex:
  22. tools:
  23. browser_navigate: { approval_mode: approve }
  24. ```
  25. Server fields:
  26. | Field | Meaning |
  27. |---|---|
  28. | `description` | Required. Shown by harnesses that support descriptions. |
  29. | `transport` | Required. `stdio` or `http`. |
  30. | `command`, `args` | `stdio` only; `command` is required. `${HOME}` is expanded at install time. |
  31. | `env` | `stdio` only. Plain values; never secrets. |
  32. | `url` | `http` only, required. |
  33. | `service` | `http` only. Compose service that must be running. |
  34. | `startup_timeout_sec` | Codex `startup_timeout_sec`; OpenCode `timeout.startup` in milliseconds. |
  35. | `requires` | Names from the top-level `requires` map. Each entry has a `check` (`path` or `command`) and a `hint`. |
  36. | `os` | `darwin`, `arch`, `debian`. Default: all. |
  37. | `harnesses` | `claude`, `codex`, `opencode`, `pi`. Default: all. |
  38. | `claude`, `codex`, `opencode`, `pi` | Harness-specific keys, written into that harness's entry verbatim. |
  39. ## Commands
  40. Run `task --list` for available commands.
  41. ## Install
  42. `scripts/installer.py` registers every server of `servers.yaml` into each harness found on PATH: Claude Code, Codex, OpenCode and Pi. It validates the manifest first and stops on any error.
  43. | Command | Effect |
  44. |---|---|
  45. | `task install` | Check `requires`, then register every applicable server. |
  46. | `task sync` | Install, update changed servers, and remove recorded servers the manifest no longer names. A second run changes nothing. |
  47. | `task uninstall` | Remove the recorded entries, then clear the state. |
  48. | `task doctor` | Also reports whether each installed harness has each server, reading config files only. |
  49. Add `-- --dry-run` to `install` or `sync` (`task install -- --dry-run`) to print the plan per harness and write nothing, not even the state file or backups. Each line is `add`, `update`, `replace`, `remove`, `unchanged` or `skip`.
  50. - A server is skipped, with the reason, when its `os` or `harnesses` exclude this machine or harness. A harness whose binary is not on PATH is skipped too.
  51. - A server with a missing `requires` dependency is skipped with `MISSING: <dependency>` and its hint. The other servers continue and the exit status is non-zero.
  52. - Claude Code and Pi are written with their own commands. Codex (`~/.codex/config.toml`) and OpenCode (`~/.config/opencode/opencode.jsonc`) are edited in place; the Codex edit keeps other tables and comments. OpenCode stops with a message if the file has comments, which an edit would drop.
  53. - **State file:** `${XDG_STATE_HOME:-~/.local/state}/agent-mcp/state.json` records, per harness, the names this repo installed and a hash of each entry.
  54. - **Backups:** before editing a file directly, the installer copies it to `<state dir>/backups/<harness>-<UTC timestamp>.<ext>`. Backups never go next to the config file.
  55. - **Replace policy:** an entry with the same name that the state file does not record is removed and registered again from the manifest, then recorded. The plan shows it as `replace`.
  56. - `uninstall` touches only recorded entries. An entry the manifest does not name, such as one added by hand, is never changed.
  57. `task test` runs the installer tests. They use temporary directories and never start a harness command.
  58. ## Secrets
  59. `secrets/secrets.sops.yaml` holds the Telegram API id and hash, encrypted with [sops](https://github.com/getsops/sops) and [age](https://github.com/FiloSottile/age); `secrets/.sops.yaml` holds the rules and `secrets/secrets.yaml.example` the plaintext template. Both tools run in one-off containers, so a host needs only Docker. Only low-value secrets belong in it: the repository is public and ciphertext stays in git history forever, so a later key leak would expose every past version.
  60. The age private key is `age/key.txt` in the repository, mode 600 in a mode-700 `age/`. Git and Docker ignore it, and it is never committed. `~/.config/sops/age` is no longer used.
  61. First machine (new key only): `task sops:generate-age-key` creates `age/key.txt`, never overwrites one, and prints the public key for `secrets/.sops.yaml`.
  62. New machine: copy `age/key.txt` once, out of band, with `age/` at mode 700 and the file at mode 600. No new key is needed.
  63. The loop, each step in your own terminal:
  64. 1. `task sops:decrypt` writes the plaintext `secrets/secrets.yaml` (ignored by git; do not commit it).
  65. 2. Edit `secrets/secrets.yaml`.
  66. 3. `task sops:encrypt` encrypts it to `secrets/secrets.sops.yaml` and removes the plaintext.
  67. Other tasks: `task sops:get -- [--copy] NAME` shows one value, only in a terminal or on the clipboard; `task sops:updatekeys` re-encrypts to the recipients in `secrets/.sops.yaml`; `task sops:validate` needs no key and fails on an unencrypted store or a leftover plaintext file.
  68. `git clean -fdx` deletes the ignored `age/key.txt`. Back the key up outside the repository: losing it makes `secrets/secrets.sops.yaml` undecryptable.
  69. ## Telegram
  70. The `telegram` server is [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp), pinned to tag `v3.3.25` and built from its upstream Dockerfile. One container serves `http://127.0.0.1:8765/mcp` to all four harnesses, so Telegram sees one connection instead of one per client. Only Docker is needed on the host. Never install the PyPI package `telegram-mcp`: it is an unrelated project.
  71. Exposed tools: read-only tools plus `send_message` and `reply_to_message` (`TELEGRAM_EXPOSED_TOOLS`). Set `TELEGRAM_EXPECTED_USERNAME` to refuse a session for the wrong account, and `TELEGRAM_TOOL_TIMEOUT_SECONDS` to change the tool timeout; both are passed to the container only when set in your shell.
  72. Warning: the port is published on `127.0.0.1` only, and the endpoint has no authentication. Any local process running as you can read and send messages with your account.
  73. Set up, once per machine:
  74. 1. `task sops:decrypt`, replace the `REPLACE_ME` placeholders in `secrets/secrets.yaml` with the real API id and hash from <https://my.telegram.org/apps>, then `task sops:encrypt`.
  75. 2. `task telegram:login`, then scan the QR code in Telegram under Settings > Devices > Link Desktop Device (and type the two-step verification password if asked). The task answers the script's prompts itself. The session string is converted into a session file and deleted; it is also printed on screen, so clear the terminal scrollback afterwards.
  76. 3. `task telegram:up`. `task doctor` reports whether the container is running and `/mcp` answers.
  77. 4. `task install` to register `telegram` in each harness.
  78. Sessions are per machine. Telegram invalidates an auth key used from two IPs at once (`AuthKeyDuplicatedError`), so never copy a session between machines: each one runs its own QR login. Use `task telegram:down` to stop the server and `task telegram:logs` to follow its logs.
  79. The session file holds account credentials. It lives in the `telegram-session` Docker volume, never in the repository, and is never committed. Voice transcripts are cached in the `telegram-transcripts` volume. To log in again, remove the volume with `docker volume rm agent-mcp_telegram-session` after `task telegram:down`.
  80. `task telegram:login` and `task telegram:up` decrypt only the API id and hash into a mode-600 temporary file outside the repository, hand it to Compose, and delete it on exit. They refuse to run while the placeholders are still in `secrets/secrets.sops.yaml`.
  81. ## Project profile
  82. This repository is initialized as a CLI foundation. Add verified project-specific build and test instructions as the implementation takes shape.
  83. ## Contributing and security
  84. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [SUPPORT.md](SUPPORT.md).
  85. ## Docker Compose
  86. Every Compose call goes through `scripts/compose.sh`, which runs `compose.example.yaml` plus the ignored `compose.override.yaml` when it exists (put machine-specific settings there). The old local copy `compose.yaml` is no longer used; delete it.
  87. | Task | Effect |
  88. |---|---|
  89. | `task docker` | build the images, then start the services |
  90. | `task docker:build` / `docker:build-nocache` | build every image, tools included |
  91. | `task docker:start` | start the services, leaving running ones alone (decrypts the Telegram credentials) |
  92. | `task docker:recreate` | recreate the services so changed secrets or settings take effect |
  93. | `task docker:stop` | stop the services, keeping containers and volumes |
  94. | `task docker:down` | remove containers and network, keeping volumes |
  95. | `task docker:restart` | `down`, then `start` |
  96. | `task docker:ps` / `docker:logs` | list containers / follow logs |
  97. | `task docker:config` | validate the Compose configuration |
  98. No task removes a volume: `agent-mcp_telegram-session` holds this machine's Telegram login. The only long-running service is `telegram`; run `task telegram:login` once before the first `task docker:start`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.