From eb8d930ed95d5f57b38802991b670ed9344bd203 Mon Sep 17 00:00:00 2001 From: Nhomar Hernandez Date: Mon, 30 Mar 2026 19:11:09 -0600 Subject: [PATCH 1/2] Docs: Add telegram_mcp_update AI skill --- .agents/skills/telegram_mcp_update/SKILL.md | 25 +++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .agents/skills/telegram_mcp_update/SKILL.md diff --git a/.agents/skills/telegram_mcp_update/SKILL.md b/.agents/skills/telegram_mcp_update/SKILL.md new file mode 100644 index 0000000..198f69b --- /dev/null +++ b/.agents/skills/telegram_mcp_update/SKILL.md @@ -0,0 +1,25 @@ +--- +name: Update Telegram MCP Tools +description: Procedure for updating the 'ALLOWED_TOOLS' environment variable in the Telegram MCP server configuration to prevent SQLite database lock issues and ensure the GUI correctly reloads the server. +--- + +# Updating Telegram MCP Tools + +**Use this skill when** the user requests updating the allowed tools for their `telegram-mcp` server or changing its configuration in `mcp_config.json`. + +Follow this precise procedure to prevent orphaned Python processes from locking the SQLite database. If the database is locked during an auto-reload, the server crashes and disappears from the IDE's MCP manager. + +## Procedure + +1. **Update Configuration**: + Edit the `ALLOWED_TOOLS` environment variable inside the `telegram-mcp` section of `mcp_config.json` with the new comma-separated tools list. + +2. **Kill Orphaned Processes**: + Whenever `mcp_config.json` is modified for this server, the IDE tries to restart it automatically. Because Telethon/Python does not always shut down cleanly, the old process stays in the background locking `telegram_session.session`. + You **MUST** proactively run the following command to terminate hanging instances BEFORE asking the user to verify (adjust the string `telegram-mcp` if the user named the directory differently): + ```bash + pkill -f "telegram-mcp" + ``` + +3. **Instruct the User to Refresh**: + Inform the user what tools were updated and explicitly ask them to click the **"Refresh"** button in their "Manage MCP servers" UI. Since the database lock was cleared by you, the server will restart correctly and reappear immediately. From 04db8cc81e5f93254c7abf31d456a8b91e982fd9 Mon Sep 17 00:00:00 2001 From: Nhomar Hernandez Date: Mon, 30 Mar 2026 19:13:53 -0600 Subject: [PATCH 2/2] Docs: Update AI skill with Open Source contribution workflow --- .agents/skills/telegram_mcp_update/SKILL.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/.agents/skills/telegram_mcp_update/SKILL.md b/.agents/skills/telegram_mcp_update/SKILL.md index 198f69b..8879b4e 100644 --- a/.agents/skills/telegram_mcp_update/SKILL.md +++ b/.agents/skills/telegram_mcp_update/SKILL.md @@ -1,13 +1,13 @@ --- name: Update Telegram MCP Tools -description: Procedure for updating the 'ALLOWED_TOOLS' environment variable in the Telegram MCP server configuration to prevent SQLite database lock issues and ensure the GUI correctly reloads the server. +description: Procedure for updating the 'ALLOWED_TOOLS' environment variable in the Telegram MCP server configuration, preventing SQLite lock issues, and contributing upstream. --- # Updating Telegram MCP Tools -**Use this skill when** the user requests updating the allowed tools for their `telegram-mcp` server or changing its configuration in `mcp_config.json`. +**Use this skill when** the user requests updating the allowed tools for their `telegram-mcp` server, changing its configuration, or sharing changes upstream via Pull Request. -Follow this precise procedure to prevent orphaned Python processes from locking the SQLite database. If the database is locked during an auto-reload, the server crashes and disappears from the IDE's MCP manager. +Follow this precise procedure to prevent orphaned Python processes from locking the SQLite database or to push changes cleanly to the Open Source project. ## Procedure @@ -15,11 +15,22 @@ Follow this precise procedure to prevent orphaned Python processes from locking Edit the `ALLOWED_TOOLS` environment variable inside the `telegram-mcp` section of `mcp_config.json` with the new comma-separated tools list. 2. **Kill Orphaned Processes**: - Whenever `mcp_config.json` is modified for this server, the IDE tries to restart it automatically. Because Telethon/Python does not always shut down cleanly, the old process stays in the background locking `telegram_session.session`. + Whenever config is modified, the IDE tries to restart the MCP automatically. Because Telethon/Python does not always shut down cleanly, the old process stays in the background locking `telegram_session.session`. You **MUST** proactively run the following command to terminate hanging instances BEFORE asking the user to verify (adjust the string `telegram-mcp` if the user named the directory differently): ```bash pkill -f "telegram-mcp" ``` 3. **Instruct the User to Refresh**: - Inform the user what tools were updated and explicitly ask them to click the **"Refresh"** button in their "Manage MCP servers" UI. Since the database lock was cleared by you, the server will restart correctly and reappear immediately. + Inform the user what tools were updated and explicitly ask them to click the **"Refresh"** button in their "Manage MCP servers" UI. The server will restart correctly. + +4. **Contributing Upstream (Pull Requests)**: + Si el usuario pide subir el código para aportar al proyecto original (`upstream`), aplica esta secuencia estandarizada: + - Revisa si el remoto secundario ya existe. Si origin es el oficial y el usuario no tiene permisos: asegúrate de tener el alias `fork` configurado apuntando a su bifurcación personal (Ej. `nhomar/telegram-mcp`). + - Genera una rama nueva: `git checkout -b feat/nombre-del-cambio`. + - Efectúa el `commit` documentando las razones concretas del cambio. + - Sube forzosamente los cambios al *fork* del usuario: `git push -f fork feat/nombre-del-cambio`. + - Emplea el cliente oficial de GitHub ubicando siempre explícitamente el repositorio principal `-R chigwell/telegram-mcp` (o el correspondiente) para levantar el PR oficial con formato documentado: + ```bash + gh pr create -R chigwell/telegram-mcp --title "Detalle formal del asunto" --body "Explicación integral del impacto de este merge" + ```