`gj҉dZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z m Z ddl m Z ddlmZddlmZmZmZej(dZd Z dd lmZd Zdd Zd ZddZd dZddZddZddZ d!dZ!d"dZ"d#dZ#dZ$dZ%e GddZ&GddZ'd$d%dZ(d&d'dZ)y#e$rdZY`wxYw)(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) dataclassfielddatetime)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 ImportErrorrosenvirongethomers entry_dict with platform routing info. state.db is the primary source (#9006): gateway sessions persist their routing metadata (session_key, chat/thread ids, display_name, origin) on the durable session row, so a single database read replaces the old dual-file sessions.json dependency. Falls back to sessions.json for pre-migration databases where no gateway rows carry a session_key yet. )_load_sessions_index_from_db_load_sessions_index_from_json)entriess r_load_sessions_indexr'Rs+,G ) ++c ti}|jd}|r( tj|}t|tr|}|sT|jdd|jd|jd|jd|jdd}dd }t|jd xsd }t|jd xsd }t|jd d|jdd|jdd|jdxs|jdd|jdxs|jdxsd|||jd||jdxs|jd||||zd S#t t f$rYxwxYw)zHConvert a state.db gateway session row to the sessions.json entry shape. origin_jsonsourcechat_id chat_type thread_iduser_id)platformr-r.r/r0c |r,tjt|jSdS#tt t f$rYywxYw)Nr,)r fromtimestampfloat isoformat TypeError ValueErrorOSError)tss r_isoz!_row_to_index_entry.._isoxsE DF8))%)4>>@ NB N:w/  s-22A A  input_tokensr output_tokensid session_key display_name chat_name started_at last_active) session_idr>r1r.r?origin created_at updated_atr;r< total_tokensreturnstr) rjsonloads isinstancedictr6r7intrJ)rowrDr*parsedr:r;r<s r_row_to_index_entryrRcs F''-(K ZZ ,F&$' "-wwy)--wwy)   sww~.3!4L05A6M#''$+,ww}b1GGHb)WW[)HVZZ R-H/P6::k3JPb377<01377=1JSWW\5JK$&$}4  ):&   s'F$$F76F7c&t}|iS t|dd}t|si |jS|d}i}|D]$}|j d}|st |||<&| |jS#t$rYSwxYw#t$rYSwxYw#t$rB}tjd|icYd}~ |jS#t$rYSwxYwd}~wwxYw# |jw#t$rYwwxYwxYw)z;Build the routing index from state.db gateway session rows.Nlist_gateway_sessionsT) active_onlyr>z1Failed to load gateway sessions from state.db: %s) r"getattrcallablecloserrrRrr )dblisterrowsr&rPkeyr!s rr$r$s  B z 4d;  HHJ$' 4C''-(C.s3GCL  4    HHJ   y     H!L   HHJ      HHJ   sB B5B 1B B B BB C+)C&C+C.C C#"C#&C++C..D0DD D  D D  Dctdz }|jsiS t|dd5}tj|}dddt t r?|jDcic]#\}}t|jdr!||%c}}SiS#1swYZxYwcc}}w#t$r"}tjd|icYd}~Sd}~wwxYw)zLegacy fallback: load the gateway sessions.json index directly. Used only for pre-migration databases whose gateway rows don't carry a session_key yet. This avoids importing the full SessionStore which needs GatewayConfig. z sessions.jsonrutf-8encodingN_z Failed to load sessions.json: %s) rexistsopenrKloadrMrNitemsrJ startswithrrr ) sessions_filefdatakvr!s rr%r%s&'/9M    !   -w 7 199Q EE&"   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. rzr,r{ image_urlurlimage)r{rr+>r|)r{rjzMEDIA:\s*(\S+)media)r{path) rrMr~rNappendrrecompilefinditergroup) r attachmentsrzpartptyperr| media_patternmatchrs r_extract_attachmentsrsh Kggi$G'4  BDdD)HHVR(E #BLTXXVaMbdhBidhh{B/33E2>oq&&'DE'!hhudhhx&<&@&@&KL&&'DEi'""E4#@A B" $C (D  #45 "++D1 @E;;q>D   > ? @ r(ig?cPeZdZUdZded<ded<dZded<eeZd ed <y ) QueueEventz)An event in the bridge's in-memory queue.rOcursorrJr{r,r>)default_factoryrNrjN) __name__ __module__ __qualname____doc____annotations__r>rrNrjr(rrr$s(3 K IKt,D$,r(rceZdZdZdZdZdZ 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|_ i|_ y)NrF) _queue_cursor threadingLock_lockEvent _new_event_running_thread_last_poll_timestamps_pending_approvals_state_db_mtime_cached_sessions_indexselfs r__init__zEventBridge.__init__5sZ(*  ^^% #//+ 37 79"35&),.#r(c|jryd|_tj|jd|_|jj t jdy)z$Start the background polling thread.NT)targetdaemonzEventBridge started)rrThread _poll_looprstartrr rs rrzEventBridge.startCsH ==   ''ttL   *+r(cd|_|jj|jr|jj dt j dy)z#Stop the background polling thread.FtimeoutzEventBridge stoppedN)rrsetrrrr rs rstopzEventBridge.stopLsB   << 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.Nrr{r>)events next_cursor)rrrr>r{rj)r after_cursorr>limitr!rrs r poll_eventszEventBridge.poll_eventsTsZZ ;;88l*$ (Du F ,2fRj''|  88QVV ! 9129 '     s"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 monotonicrrrr>r{rjrclearwaitrr POLL_INTERVAL)rrr> timeout_msdeadliner! remainings rwait_for_eventzEventBridge.wait_for_eventls>>#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)NrEr,r)as rz4EventBridge.list_pending_approvals..saeeL"5r()r\N)rsortedrvaluesrs rlist_pending_approvalsz"EventBridge.list_pending_approvalss; ZZ ''..05   s &=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_resolvedr>r,) approval_iddecisionrr{r>rjT)resolvedrr)rrpop_enqueuerr)rrrapprovals rrespond_to_approvalzEventBridge.respond_to_approvals ZZ F..22;EH F3K=AB B j$ ]B7!,(C   !(SS F Fs 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.rrN) rrrrrlen QUEUE_LIMITrrr)revents rrzEventBridge._enqueues ZZ # LLA L<# JJ} % mm > 91== >sA)) B2B  Bc ddlm}|dz } |jr|jjnd}||jk(ry||_ t|_|j}|jD]f\}}|j dd }|s|j j |d} |j#|} | sMdd } g} | D]H} | | j d d}| j d d }|d vr2|| kDs8| j'| J| D]x} t)| }|s|j+t-dd|| j d d |ddt/| j d d t/| j dd dz| Dcgc]}| |j d d}}|sFt1|}|| kDsX||j |<iy#t$rEttj j dtjdz dz }Y'wxYw#t$rd}Y wxYw#t$$rYwxYwcc}w)u"Check for new messages across all sessions. Uses a single mtime check on state.db to skip work when nothing has changed — makes 200ms polling essentially free. Since #9006 the routing index itself lives in state.db (session rows carry session_key/origin metadata), so a new conversation and its first message land in the SAME file and one mtime check covers both — eliminating the old dual-file (sessions.json + state.db) race that could drop brand-new conversations (#8925). rrzstate.dbrrrNrCr,ct|ttfr t|St|tr|r t|Sy#t$r: ddlm}|j |jcYS#t$rYYywxYwwxYw)Nrrr) rMrOr4rJr7r fromisoformat timestampr)r9rs r _ts_floatz)EventBridge._poll_once.._ts_floatsb3,/ 9$b#&2'$Ry(&''9#98#9#9"#=#G#G#II('#&' 's/ A B %A30B3 B<B?BBrrole>user assistantmessageir=)rrzr message_idr)rIr4)rrrrrrrrrcstatst_mtimer8rr'rrfr get_messagesrrrrrrJrq)rrYrdb_filedb_mtimer&r>entryrC last_seenmessagesr new_messagesrr9rrzmall_tslatests rrzEventBridge._poll_oncesh ` 8%'*4G 29..2Bw||~..H t++ + '';&<#--")--/> E K<4J2266{CHI ??:6  L -sww{A67wwvr*44 > '',  -$ 237 j" + # 3#*4C=%(b)A%B&)#''$*;&<     "AII1ik1 56IFIVI%>DD..{;}> E% `2::>>-y9PQRU__G `  H ,  bJs;G,,H=:I"I,A H:9H:= I  I  IIrN)rrOr> Optional[str]rrOrIrNrN0u)rrOr>rrrOrIzOptional[dict])rI List[dict])rrJrrJrIrN)rrrINone)rrrrrrrrrrrrrrrr(rrr-s /,,%)   #     4%) #   8T"  &^Er(rc 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 2rrtrurvrDr1r,r?r@rCr. user_namerF)r>rCr1r.r?r@rrFc&|jddS)NrFr,r)cs rrz?create_mcp_server..conversations_list..cs|R)@r(T)r\reverseN)count conversationsindent) rxr'rfrlowerrsortrKdumpsr) r1rsearchr&rr\rrDentry_platformr?r@ search_lowers rconversations_listz-create_mcp_server..conversations_list4s 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: rDrCr,r1r.r?rr@r-r/rFrEr;rr<rG)r>rCr1r.r?rr@r-r/rFrEr;r<rGrr)r'rrKr)r>r&rrDs rconversation_getz+create_mcp_server..conversation_getms4'( 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) rrrrrr#rCr,#No session ID for this conversationSession database unavailableFailed to read messages: Nr>rrr=ir)r=rrzr)r>rtotal_in_sessionrrr) rxr'rrKrr"rrrrrJr) r>rr&rrCrY all_messagesr!filteredrrrzrs r messages_readz(create_mcp_server..messages_readsE2q#F&( K(::w*B;-(PQR RYY|R0 ::w(MNO O  ::w(FGH H J??:6L C7762&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 rr#rCr,r&r'r(Nr=zMessage not found: )rrrrr) r'rrKrr"rrrJrr) r>rr&rrCrYr*r! target_msgrrs rattachments_fetchz,create_mcp_server..attachments_fetchsO'( 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) rNZorrrr)rr>rrr)rxrrKr)rr>rresultbridges 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) rr1rri)rr>rrrrNr)rreason)rxrrKr)rr>rrr3s 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)rKrtools.send_message_toolr9rr)rrr9 result_strr!s r messages_sendz(create_mcp_server..messages_send:s(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.) rDr1r,r-:r?r@r.)rr1namer.)rchannelsrr platformsr=rAr{)ror'rrfrraddrrKrrrMr~rN)r1 directoryr&targetsseenr\rrDrr- target_strrBplat entries_listchs r channels_listz(create_mcp_server..channels_list^s,- *,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)+); ) zzCMxHQRSSr(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)rrKrr)rNr3s rpermissions_list_openz0create_mcp_server..permissions_list_opens8113 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)rKrr)r=rr2r3s rpermissions_respondz.create_mcp_server..permissions_responds_ A A::-hZ8EF  ++B9zz&++r()NrN)r1rrrOrrrIrJ)r>rJrIrJ)r)r>rJrrOrIrJ)r>rJrrJrIrJr)rrOr>rrrOrIrJr)rrOr>rrrOrIrJ)rrJrrJrIrJN)r1rrIrJrH)r=rJrrJrIrJ)_MCP_SERVER_AVAILABLErsys executabler rtool) event_bridgemcpr!r$r,r/r4r7r>rLrOrTr3s @rcreate_mcp_serverr\s[   ^^,,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._runs6 ((* * * KKM + KKMs%A0.0A0AA)rVprintrWrXstderrexitlogging basicConfigDEBUGWARNINGrrr\asynciorunKeyboardInterruptr)verboserlrdr3rcs @@rrun_mcp_serverrps    ^^,,A C  '-- C'//#**E ]F LLN F 3F  DF  s%C<<DD)rIr)rIrN)rPrNrIrN)rtrOrurOrvrOrIrO)rrNrIrJ)rrNrIrrU)rZzOptional[EventBridge]rIz 'FastMCP')F)roboolrIr )*r __future__rrKrhrrrWrr dataclassesrrrpathlibrtypingr r r getLoggerrrVmcp.server.fastmcpr rrr"r'rRr$r%rorxrrrrrrr\rprr(rrxs:#   (''   - . * Y,")X62(// /  /  /& +#T   -- -kEkEdY@ QGsB77CC