j{ddZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z m Z ddl mZddlmZmZmZej&dZdZ dd lmZd Zdd Zd Zdd ZddZ ddZddZddZdZ dZ!e GddZ"GddZ#dd dZ$d!d"dZ%y#e$rdZYTwxYw)#uA Hermes MCP Server — expose messaging conversations as MCP tools. Starts a stdio MCP server that lets any MCP client (Claude Code, Cursor, Codex, etc.) list conversations, read message history, send messages, poll for live events, and manage approval requests across all connected platforms. Matches OpenClaw's 9-tool MCP channel bridge surface: conversations_list, conversation_get, messages_read, attachments_fetch, events_poll, events_wait, messages_send, permissions_list_open, permissions_respond Plus: channels_list (Hermes-specific extra) Usage: hermes mcp serve hermes mcp serve --verbose MCP client config (e.g. claude_desktop_config.json): { "mcpServers": { "hermes": { "command": "hermes", "args": ["mcp", "serve"] } } } ) annotationsN) dataclassfield)Path)DictListOptionalzhermes.mcp_serveF)FastMCPTc ddlm}|dz S#t$rDttj j dtjdz dz cYSwxYw)z0Return the sessions directory using HERMES_HOME.rget_hermes_homesessions HERMES_HOME.hermes)hermes_constantsr ImportErrorrosenvirongethomer s /home/cube/projects/richard/traning coach/.omo/evidence/nutricoach-v150-combined/st_01a0560c-r63-installed-wheel-first-claim-qa/venv/lib/python3.12/site-packages/mcp_serve.py_get_sessions_dirr>sTY4 :-- YBJJNN=$))+ 2IJKjXXYsA AAcv ddlm}|S#t$r }tj d|Yd}~yd}~wwxYw)z9Get a SessionDB instance for reading message transcripts.r) SessionDBzSessionDB unavailable: %sN) hermes_stater Exceptionloggerdebug)res r_get_session_dbr Gs4*{  0!4s  838ctdz }|jsiS t|dd5}tj|cdddS#1swYyxYw#t $r"}t jd|icYd}~Sd}~wwxYw)zLoad the gateway sessions.json index directly. Returns a dict of session_key -> entry_dict with platform routing info. This avoids importing the full SessionStore which needs GatewayConfig. sessions.jsonrutf-8encodingNz Failed to load sessions.json: %s)rexistsopenjsonloadrrr) sessions_filefrs r_load_sessions_indexr-Qso &'/9M    !  -w 7199Q<8 7 7  7; s:AA AAAA B#B:BBc ddlm}|dz }|jsiS t|dd5}tj|cd d d S#t$rDttj j dtjdz dz }YwxYw#1swYy xYw#t$r"}tjd |icYd }~Sd }~wwxYw) z8Load the cached channel directory for available targets.rr zchannel_directory.jsonrrr#r$r%Nz)Failed to load channel_directory.json: %s)rr rrrrrrr'r(r)r*rrr)r directory_filer,rs r_load_channel_directoryr0bs%4(*-EE  "  .# 8A99Q<9 8 % JJNN=$))+ *A B $%%9 8  @!D sLAB.B" B.A BB"B+'B.+B.. C7CCCct t|}t|t ||S#ttf$r|}Y)wxYw)zCoerce value to int with fallback and clamping. Used at MCP tool boundaries to handle invalid types from external clients. Returns default if value cannot be converted to int. )int TypeError ValueErrormaxmin)valuedefaultminimummaximumcoerceds r _coerce_intr<vsAe* wGW- .. z "s #77c|jdd}t|trT|Dcgc]8}t|tr&|jddk(r|jdd:}}dj |S|r t |SdScc}w)zAExtract text content from a message, handling multi-part content.contenttypetext )r isinstancelistdictjoinstr)msgr>p text_partss r_extract_message_contentrKsggi$G'4 '. '.!!T"quuV}'> EE&" w  yy$$"3w<**  s=Bcg}|jdd}t|tr|D]}t|ts|jdd}|dk(r[t|jdtr"|jdijddnd}|sq|j d|d|dk(rJ|jd|jdijdd}|s|j d|d|d vs|j ||d t |}|rPt jd }|j|D]'}|jd } |j d | d)|S)zExtract non-text attachments from a message. Finds: multi-part image/file content blocks, MEDIA: tags in text, image URLs, and file references. r>r?r@ image_urlurlimage)r@rNsource>rA)r@datazMEDIA:\s*(\S+)media)r@path) rrCrDrEappendrKrecompilefinditergroup) rH attachmentsr>partptyperNrA media_patternmatchrTs r_extract_attachmentsr_sZ Kggi$G'4 DdD)HHVR(E #BLTXXVaMbdhBidhh{B/33E2>oq&&'DE'!hhudhhx&<&@&@&KL&&'DEi'""E4#@A" $C (D  #45 "++D1E;;q>D   > ?2 ig?cPeZdZUdZded<ded<dZded<eeZd ed <y ) QueueEventz)An event in the bridge's in-memory queue.r2cursorrGr@r? session_key)default_factoryrErQN) __name__ __module__ __qualname____doc____annotations__rdrrErQr`rrbrbs(3 K IKt,D$,r`rbceZdZdZdZdZdZ d ddZ d ddZddZ dd Z dd Z d Z d Z y) EventBridgeaBackground poller that watches SessionDB for new messages and maintains an in-memory event queue with waiter support. This is the Hermes equivalent of OpenClaw's WebSocket gateway bridge. Instead of WebSocket events, we poll the SQLite database for changes. cg|_d|_tj|_tj |_d|_d|_i|_ i|_ d|_ d|_ i|_ y)NrF)_queue_cursor threadingLock_lockEvent _new_event_running_thread_last_poll_timestamps_pending_approvals_sessions_json_mtime_state_db_mtime_cached_sessions_indexselfs r__init__zEventBridge.__init__sb(*  ^^% #//+ 37 79"35+.!&),.#r`c|jryd|_tj|jd|_|jj t jdy)z$Start the background polling thread.NT)targetdaemonzEventBridge started)rwrrThread _poll_looprxstartrrr~s rrzEventBridge.startsH ==   ''ttL   *+r`cd|_|jj|jr|jj dt j dy)z#Stop the background polling thread.FtimeoutzEventBridge stoppedN)rwrvsetrxrFrrr~s rstopzEventBridge.stopsB   << LL  a  ( *+r`Ncz|j5|jDcgc]$}|j|kDr|r|j|k(r|&c}d|}dddr|djn|}|Dcgc]2}|j|j|jd|j 4c}|dScc}w#1swYbxYwcc}w)zEReturn events since after_cursor, optionally filtered by session_key.Nrcr@rd)events next_cursor)rtrprcrdr@rQ)r after_cursorrdlimitrrrs r poll_eventszEventBridge.poll_eventssZZ;;&a88l*$ (D;u F,2fRj''|   A88QVV ! 9129 '   Zs"B,)B'B,*7B8'B,,B5cxtj|dz z}tj|kr|j5|jD]^}|j|kDs|r|j |k(s%|j|j |j d|jccdddS ddd|tjz }|dkr y|jj|jjt|ttj|kry#1swYxYw)z8Block until a matching event arrives or timeout expires.g@@rNrr) time monotonicrtrprcrdr@rQrvclearwaitr6 POLL_INTERVAL)rrrd timeout_msdeadliner remainings rwait_for_eventzEventBridge.wait_for_event s>>#zF':;nn)Axx,.'1==K+G'(hh+,== <=FF  $!4>>#33IA~ OO ! ! # OO Y )F Gnn)"!sD0D001D0+D00D9c|j5t|jjdcdddS#1swYyxYw)z;List approval requests observed during this bridge session.c&|jddS)N created_atr?r)as rz4EventBridge.list_pending_approvals..-saeeL"5r`)keyN)rtsortedrzvaluesr~s rlist_pending_approvalsz"EventBridge.list_pending_approvals(s0 ZZ''..05ZZs &=Ac |j5|jj|d}dddsdd|iS|jt dd|j dd||d d ||d S#1swYIxYw) z=Resolve a pending approval (best-effort without gateway IPC).NerrorzApproval not found: rapproval_resolvedrdr?) approval_iddecisionrcr@rdrQT)resolvedrr)rtrzpop_enqueuerbr)rrrapprovals rrespond_to_approvalzEventBridge.respond_to_approval0s ZZ..22;EH3K=AB B j$ ]B7!,(C   !(SSZs A22A;c|j5|xjdz c_|j|_|jj |t |jt kDr8|jjdt |jt kDr8ddd|jjy#1swY$xYw)z/Add an event to the queue and wake any waiters.rRrN) rtrqrcrprUlen QUEUE_LIMITrrvr)revents rrzEventBridge._enqueueAs ZZ LLA L<# JJ} % mm > 91== >sA)) B2B  Bctdz } |jr|jjnd}||j k7r||_t |_ ddlm }|dz } |jr|jjnd}||j k(r||j k(ry||_|j}|j#D]f\}} | jd d } | s|j$j|d} |j'| } | sMdd } g}| D]H}| |jd d}|jd d }|dvr2|| kDs8|j+|J|D]x}t-|}|s|j/t1dd||jd d |ddt3|jd d t3|jdd dz| Dcgc]}| |jd d}}|sFt5|}|| kDsX||j$|<iy#t$rd}YwxYw#t$rEttjjdtjdz dz }Y9wxYw#t$rd}YwxYw#t($rYwxYwcc}w)uCheck for new messages across all sessions. Uses mtime checks on sessions.json and state.db to skip work when nothing has changed — makes 200ms polling essentially free. r"rorr zstate.dbrrN session_idr?c t|ttfr t|St|tr|r t|Sy#t$r9 ddlm}|j |jcYS#t$rYYywxYwwxYw)Nr)datetimero) rCr2floatrGr4r fromisoformat timestampr)tsrs r _ts_floatz)EventBridge._poll_once.._ts_floatsb3,/ 9$b#&2'$Ry(&''9#+#9#9"#=#G#G#II('#&' 's/ A B $A2/B2 A?;B>A??Brrole>user assistantmessageiid)rr>r message_idr)returnr)rr'statst_mtimeOSErrorr{r-r}rr rrrrrrr|itemsry get_messagesrrUrKrrbrGr5)rrr+sj_mtimer db_filedb_mtimeentriesrdentryr last_seenmessagesr new_messagesrHrrr>mall_tslatests rrzEventBridge._poll_onceZs*+o=  8E8L8L8N}))+44TWH t00 0(0D %*>*@D ' ` 8%'*4G 29..2Bw||~..H t++ +D '',  $237 j" + # 3#*4C=%(b)A%B&)#''$*;&<    $"AII1ik1 56FIVI%>DD..{;}#23 H  `2::>>-y9PQRU__G `  H $  bJsN,I !I2,J.KK IIA J+*J+. J=<J= K  K rN)rr2rd Optional[str]rr2rrErN0u)rr2rdrrr2rzOptional[dict])r List[dict])rrGrrGrrE)rrbrNone)rfrgrhrirrrrrrrrrrrkr`rrmrms /,,%)   #     4%) #   8T"  &aEr`rmc tstdtjdt dd}|xs t |j d dd}|j dd}|j d dd}|j dd }|j d d fd }|j d d fd }|j dd }|j ddd } |j d fd } |j d fd } |S)zBCreate and return the Hermes MCP server with all tools registered.z5MCP server requires the 'mcp' package. Install with:  -m pip install 'mcp'hermeszHermes Agent messaging bridge. Use these tools to interact with conversations across Telegram, Discord, Slack, WhatsApp, Signal, Matrix, and other connected platforms.) instructionscHt|ddd}t}g}|jD]8\}}|jdi}|jdxs|jdd}|r"|j |j k7rb|jdd} |jd d} |rG|j } | | j vr%| | j vr| |j vr|j ||jd d||jd |jd d| | |jd d|jd dd;|j dd|d|}tjt||ddS)aList active messaging conversations across connected platforms. Returns conversations with their session keys (needed for messages_read), platform, chat type, display name, and last activity time. Args: platform: Filter by platform name (telegram, discord, slack, etc.) limit: Maximum number of conversations to return (default 50) search: Optional text to filter conversations by name 2rRr8r9r:originplatformr? display_name chat_namer chat_type user_name updated_at)rdrrrrrrrc&|jddS)Nrr?r)cs rrz?create_mcp_server..conversations_list..s|R)@r`T)rreverseN)count conversationsindent) r<r-rrlowerrUsortr)dumpsr) rrsearchrrrrrentry_platformrr search_lowers rconversations_listz-create_mcp_server..conversations_lists E2q#F&( !--/JCYYx,F"YYz2PfjjR6PNN002hnn6FF 99^R8L ;3I%||~  (:(:(<<( 0AA( ;  "#ii b9*"YY{FJJ{B4OP ,&#ZZ R8#ii b9 " !*6 @$O%fu- zz'*  r`ct}|j|}|stjdd|iS|jdi}tj||jdd|jdxs|jdd|jd|jdd|jdd|jd d|jd d|jd d|jd |jd d|jdd|jdd|jdd|jddddS)zGet detailed info about one conversation by its session key. Args: session_key: The session key from conversations_list rConversation not found: rrr?rrrrrchat_id thread_idrr input_tokensr output_tokens total_tokens)rdrrrrrrrrrrrrrrr)r-rr)r)rdrrrs rconversation_getz+create_mcp_server..conversation_gets4'( K(::w*B;-(PQR R8R(zz&))L"5 *-KJ1K; ;0KL!IInb9K4K4zz)R0K0))L"5))L"5!IIna8"YY:!IIna8  r`c t|ddd}t}|j|}|stjdd|iS|jdd}|stjdd iSt }|stjdd iS |j |}g}|D]i} | jd d} | dvst| } | s(|jt| jdd| | d d| jdddk|| d } tj|t| t|| ddS#t$r$}tjdd |icYd }~Sd }~wwxYw)aLRead recent messages from a conversation. Returns the message history in chronological order with role, content, and timestamp for each message. Args: session_key: The session key from conversations_list limit: Maximum number of messages to return (default 50, most recent) rrRrrrrrr?#No session ID for this conversationSession database unavailableFailed to read messages: Nr>rrrir)rrr>r)rdrtotal_in_sessionrrr) r<r-rr)rr rrrKrUrGr) rdrrrrr all_messagesrfilteredrHrr>rs r messages_readz(create_mcp_server..messages_read1sE2q#F&( K(::w*B;-(PQR RYY|R0 ::w(MNO O  ::w(FGH H J??:6LC7762&D,,237OO!#''$"34 $#*5D>%(WW["%= %  UFG$zz&] #H     % J::w*CA3(GHI I JsE E8E3-E83E8c|t}|j|}|stjdd|iS|jdd}|stjddiSt }|stjddiS |j |}d}|D]$} t| jd d|k(s"| }n|stjdd |iSt|} tj|t| | d d S#t $r$}tjdd|icYd}~Sd}~wwxYw)a:List non-text attachments for a message in a conversation. Extracts images, media files, and other non-text content blocks from the specified message. Args: session_key: The session key from conversations_list message_id: The message ID from messages_read rrrr?r r r NrzMessage not found: )rrrZrr) r-rr)rr rrrGr_r) rdrrrrrrr target_msgrHrZs rattachments_fetchz,create_mcp_server..attachments_fetchjsJ'( K(::w*B;-(PQR RYY|R0 ::w(MNO O  ::w(FGH H J??:6L  C3774$%3  ::w*=j\(JKL L*:6 zz$%&    J::w*CA3(GHI I JsD D;D60D;6D;ct|ddd}t|ddd}j|||}tj|d S) aPoll for new conversation events since a cursor position. Returns events that have occurred since the given cursor. Use the returned next_cursor value for subsequent polls. Event types: message, approval_requested, approval_resolved Args: after_cursor: Return events after this cursor (0 for all) session_key: Optional filter to one conversation limit: Maximum events to return (default 20) rNZorrrRr)rrdrrr)r<rr)r)rrdrresultbridges r events_pollz&create_mcp_server..events_pollsV$#<AvV E2q#F##%#$  zz&++r`ct|ddd}t|ddd}j|||}|rtjd|id Stjd d d d S) aWait for the next conversation event (long-poll). Blocks until a matching event arrives or the timeout expires. Use this for near-real-time event delivery without polling. Args: after_cursor: Wait for events after this cursor session_key: Optional filter to one conversation timeout_ms: Maximum wait time in milliseconds (default 30000) rrrri)rrdrrrrNr)rreason)r<rr)r)rrdrrrs r events_waitz&create_mcp_server..events_waits| #<AvV    %%%#!&  ::w.q9 9zzDI>qIIr`c|r|stjddiS ddlm}|d||d}|S#t$rtjddicYSt $r$}tjdd|icYd }~Sd }~wwxYw) uSend a message to a platform conversation. The target format is "platform:chat_id" — same format used by the channels_list tool. You can also use human-friendly channel names that will be resolved automatically. Examples: target="telegram:6308981865" target="discord:#general" target="slack:#engineering" Args: target: Platform target in "platform:identifier" format message: The message text to send rz$Both target and message are requiredr)send_message_toolsend)actionrrzSend message tool not availablez Send failed: N)r)rtools.send_message_toolrrr)rrr result_strrs r messages_sendz(create_mcp_server..messages_sends(W::w(NOP P > A*!VHJ  L::w(IJK K >::w-s(;<= = >s!1 A?A?A:4A?:A?c t}|s9t}g}t}|jD]\}}|j di}|j dxs|j dd}|j dd} |r| sT|r"|j |j k7rx|d| } | |vr|j | |j| ||j dxs|j dd|j d|j ddd tjt||d d Sg} |j d ijD]\} } |r"| j |j k7r*t| ts;| D]}t|ts|j d|j dd} | j| r| d| n| | |j d|j dd|j ddd tjt| | d d S)a:List available messaging channels and targets across platforms. Returns channels that you can send messages to. The target strings returned here can be used directly with the messages_send tool. Args: platform: Filter by platform name (telegram, discord, slack, etc.) rrr?r:rrr)rrnamer)rchannelsrr platformsrr&r@)r0r-rrrraddrUr)rrrCrDrE)r directoryrtargetsseenrrrrIr target_strr'plat entries_listchs r channels_listz(create_mcp_server..channels_lists,- *,GG5D%mmo U8R0IIj)GVZZ B-G **Y3 X^^-= = !s!G9- %$( !!IIn5TKQS9T!&; ;PR8S!T  .$::G 'JSTU U"+-- R"@"F"F"H D,DJJLHNN,<<,-&B!"d+"$&&rvvi/D"E =Day&9$(,$&FF6266."3M$N)+); )' #IzzCMxHQRSSr`cjj}tjt||ddS)u!List pending approval requests observed during this bridge session. Returns exec and plugin approval requests that the bridge has seen since it started. Approvals are live-session only — older approvals from before the bridge connected are not included. )r approvalsrr)rr)rr)r3rs rpermissions_list_openz0create_mcp_server..permissions_list_open7s8113 zz^"  r`c|dvrtjdd|diSj||}tj|dS)zRespond to a pending approval request. Args: id: The approval ID from permissions_list_open decision: One of "allow-once", "allow-always", or "deny" > allow-once allow-alwaysdenyrzInvalid decision: z+. Must be allow-once, allow-always, or denyrr)r)rr)rrrrs rpermissions_respondz.create_mcp_server..permissions_respondGs_ A A::-hZ8EF  ++B9zz&++r`)NrN)rrrr2rrrrG)rdrGrrG)r)rdrGrr2rrG)rdrGrrGrrGr)rr2rdrrr2rrGr)rr2rdrrr2rrG)rrGrrGrrGN)rrrrG)rrG)rrGrrGrrG)_MCP_SERVER_AVAILABLErsys executabler rmtool) event_bridgemcprr rrrrr#r1r4r9rs @rcreate_mcp_serverrAs[   ^^,,A C   5 C *[]F XXZ"& $4444 44p XXZ@ XXZ444 44p XXZ/// //f XXZ%),,",, ,,8 XXZ%)JJ"JJ JJB XXZ>>> >>F XXZ1T1Tj XXZ   XXZ, ,, ,,& Jr`c6tsBtdtjdtjtj d|r4t jt jtjn3t jt jtjtjtddl }fd } |j|y#t$rj!YywxYw) z%Start the Hermes MCP server on stdio.z._runxs6 ((* * * KKM + KKMs%A0.0A0AA)r;printr<r=stderrexitlogging basicConfigDEBUGWARNINGrmrrAasynciorunKeyboardInterruptr)verboserQrIrrHs @@rrun_mcp_serverrUbs    ^^,,A C  '-- C'//#**E ]F LLN F 3F  DF  s%C<<DD)rr)rrE)r8r2r9r2r:r2rr2)rHrErrG)rHrErrr:)r?zOptional[EventBridge]rz 'FastMCP')F)rTboolrr)&ri __future__rr)rMrrVr<rrr dataclassesrrpathlibrtypingrrr getLoggerrr;mcp.server.fastmcpr rrr r-r0r<rKr_rrrbrmrArUrkr`rr]s:#   (''   - . * Y"(// /  /  /& +#T   -- -oEoElY@ YGsB%%B/.B/