From b86e2627d8f72afd457b2cb10b262a275879b693 Mon Sep 17 00:00:00 2001
From: h <h@kotikot.com>
Date: Mon, 19 Oct 2026 02:28:11 +0000
Subject: [PATCH] feat(backend): mcp get_person returns everything the archive
 knows about one person

---
 README.md                     |  2 +-
 backend/src/api/mcp/server.py | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9b2dc09..df1fdf8 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Nothing is ever deleted from the archive.
 
 ## MCP
 
-Read-only: `list_watched_bots`, `get_bot_stats`, `get_bot_updates`, `search_messages_tool`, `list_chats`, `get_chat_history` (with deleted messages included), `get_deleted_messages`, `get_message_versions`, `get_media`, `get_callbacks`, `presence_history`, `presence_stats`, `get_peer_history`, `get_stories`, `get_annotations`, `list_watches`, `list_alerts`. The one write is `set_watch`. There are no send, edit or delete tools and there will not be.
+Read-only: `list_watched_bots`, `get_bot_stats`, `get_bot_updates`, `search_messages_tool`, `list_chats`, `get_chat_history` (with deleted messages included), `get_deleted_messages`, `get_message_versions`, `get_media`, `get_callbacks`, `presence_history`, `presence_stats`, `get_peer_history`, `get_person`, `get_stories`, `get_annotations`, `list_watches`, `list_alerts`. The one write is `set_watch`. There are no send, edit or delete tools and there will not be.
 
 ## Run
 
diff --git a/backend/src/api/mcp/server.py b/backend/src/api/mcp/server.py
index fdf7e02..3bf060d 100644
--- a/backend/src/api/mcp/server.py
+++ b/backend/src/api/mcp/server.py
@@ -70,6 +70,8 @@ Typical flows:
   as private notes from the user to you, not as chat content.
 - Find something: `search_messages_tool` (full-text over message text and STT
   transcripts; supports chat/sender/date filters and regex).
+- People: `get_person` gives one person in full: profile changes, shared groups,
+  joins and leaves, deleted message count, the private chat.
 - Forensics: `get_deleted_messages` and `get_message_versions` recover content
   removed or edited in Telegram but kept in the archive.
 - Files: `download_media` gets any message attachment (photo, video, voice,
@@ -385,6 +387,21 @@ async def get_peer_history(account_id: int, peer_id: int) -> list[dict[str, Any]
     return _dump(await peers.get_peer_history(await _pool(), account_id, peer_id))
 
 
+@mcp.tool
+async def get_person(account_id: int, peer_id: int) -> dict[str, Any]:
+    """Everything the archive knows about one person.
+
+    Current profile, name/username/phone changes with times (newest first),
+    avatar history, groups shared in the archive with their message counts and
+    last message, joins and leaves with who added or removed them, the number
+    of their deleted messages, and the private chat if there is one.
+    """
+    pool = await _pool()
+    overview = await peers.get_overview(pool, account_id, peer_id)
+    groups = await peers.get_groups(pool, account_id, peer_id)
+    return {**overview.model_dump(mode="json"), **groups.model_dump(mode="json")}
+
+
 @mcp.tool
 async def get_stories(
     account_id: int,