$jE_ LUdZddlZddlZddlZddlmZddlmZddlm Z ddlm Z ddl m Z ddlmZdd lmZmZdd lmZdd lmZmZmZdd lmZejd dZejej ej!ej"ej#ej#dZ$ej%e$eej"dej&e'Z(ejddZ)ejdZ*eddZ+ee,dze-d<eddZ.ee,dze-d<eddZ/ee,dze-d<eddZ0ee,dze-d<eddZ1ee2e-d <d!e,dzfd"Z3d!e,dzfd#Z4d!e,dzfd$Z5d!e,dzfd%Z6d!e2fd&Z7d8d(e d)e2d!efd*Z8d+ed!e9fd,Z:d+ed!dfd-Z;d.e9d/e,d0eGd5d6Z?d(e fd7Z@dS)9zCHindsight MCP Server implementation using FastMCP (HTTP transport).N) ContextVar)FastMCP) MemoryEngine) __version__)_get_raw_config)_current_schema) MCPExtensionload_extension)AuthenticationError) _ALL_TOOLSMCPToolsConfigregister_mcp_tools)RequestContextHINDSIGHT_API_LOG_LEVELinfo)criticalerrorwarningrdebugtracez4%(asctime)s - %(levelname)s - %(name)s - %(message)s)levelformatHINDSIGHT_MCP_BANK_IDdefaultHINDSIGHT_API_MCP_AUTH_TOKENcurrent_bank_id)r_current_bank_idcurrent_api_key_current_api_keycurrent_tenant_id_current_tenant_idcurrent_api_key_id_current_api_key_idcurrent_mcp_authenticatedF_current_mcp_authenticatedreturnc4tS)z%Get the current bank_id from context.)rget]/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/hindsight_api/api/mcp.pyget_current_bank_idr,8    ! !!r*c4tS)z%Get the current API key from context.)rr(r)r*r+get_current_api_keyr/=r-r*c4tS)z'Get the current tenant_id from context.)r!r(r)r*r+get_current_tenant_idr1Bs  ! ! # ##r*c4tS)z(Get the current api_key_id from context.)r#r(r)r*r+get_current_api_key_idr3Gs  " " $ $$r*c4tS)zDGet whether the request was pre-authenticated by MCP transport auth.)r%r(r)r*r+get_current_mcp_authenticatedr5Ls % ) ) + ++r*Tmemory multi_bankc tdt}t}thd}|rdn|}|j"t|j}||nt |z}t ttttt||}t|||tdt}|r=td|jj|||t)||S)aU Create and configure the Hindsight MCP server. Args: memory: MemoryEngine instance (required) multi_bank: If True, expose all tools with bank_id parameters (default). If False, only expose bank-scoped tools without bank_id parameters. Returns: Configured FastMCP server instance zhindsight-mcp-server)version>recallretainreflectget_bank list_tags get_memory delete_bank sync_retain update_bank get_document get_operation list_memoriesclear_memorieslist_documentsdelete_documentlist_directiveslist_operationscancel_operationcreate_directivedelete_directiveget_mental_modellist_mental_modelscreate_mental_modeldelete_mental_modelupdate_mental_modelrefresh_mental_modelN)bank_id_resolverapi_key_resolvertenant_id_resolverapi_key_id_resolvermcp_authenticated_resolverinclude_bank_id_paramtoolsMCPzLoading MCP extension: )rHINDSIGHT_VERSIONr frozensetmcp_enabled_toolsr r r,r/r1r3r5rr r loggerr __class____name__register_tools_make_tools_tolerant) r6r7mcp global_config_SINGLE_BANK_TOOLS base_toolsallowedconfig mcp_extensions r+create_mcp_serverrkQs' (2C D D DC#%%M*3   **<1;(R@RJ&2M;<<$.$:jj gU ,,02#@(FsFF+++#5,77M2 Pm.E.NPPQQQ$$S&111 Jr*rdct|dr |jjSt|dr(d|jjDSd}t |)uDGet tool name→object mapping, compatible with FastMCP 2.x and 3.x. _tool_manager_local_providerci|]O\}}|d|dddd|PS)ztool::@r) startswithsplit.0kvs r+ z"_get_mcp_tools..sa   1||G$$ GGCLLO ! !# & &q )1   r*z'Cannot locate tools on FastMCP instance)hasattrrm_toolsrn _componentsitemsAttributeError)rdmsgs r+_get_mcp_toolsrs}sO$$( ''s%&&   +7==??    4C   r*c^ t|}|D]\}}t|dr|jr|jdi}t |}t }t }|D]\}} t| ||||j} || ||fd} t |d| dS#ttf$r(} td| Yd} ~ dSd} ~ wwxYw)aWrap all tool run methods to strip unknown arguments and coerce string-encoded JSON. LLMs frequently add extra fields like "explanation" or "reasoning" to tool calls. FastMCP's Pydantic TypeAdapter rejects these with "Unexpected keyword argument". LLMs also frequently serialize list/dict arguments as JSON strings instead of native types (e.g., tags='["a","b"]' instead of tags=["a","b"]). This auto-coerces them. This wraps each tool's run() to apply both fixes before validation. parameters propertiescKt|z }|r=td|fd|D}t |||}||d{VS)Nz,Stripping unknown arguments from tool call: c$i|] \}}|v || Sr)r))rvrwrx_alloweds r+ryz?_make_tools_tolerant.._tolerant_run..s%$Y$Y$Yda1PX==Q===r*)setkeysr_rr}_coerce_string_json) argumentsr_orig _array_params_object_params extra_keyss ` r+ _tolerant_runz+_make_tools_tolerant.._tolerant_runs"%Y^^%5%5!6!6!AJ!Z %`T^%`%`aaa$Y$Y$Y$Yioo6G6G$Y$Y$Y !4I}n ] ]I!&y!1!11111111r*runz2Could not make tools tolerant of extra arguments: N)rr}rzrr(rr_collect_coercible_typesrobject __setattr__r~KeyErrorr_r) rdrZnametoolrrh array_params object_params param_name param_schema original_runres r+rcrcsn&Qs##++--" ?" ?JD$t\**! ?t! ?!_00rBB joo//00 *- *-%% 0:0@0@0B0Bdd,J ,\:|Ubcccc#x %&".#0 2222&""4 >>>E" ?" ?F H %QQQOAOOPPPPPPPPPQsC/C33D,D''D,schemarrrc|d}|dkr||dS|dkr||dS|dg|dgzD]S}|d}|dkr||dS|dkr||dSTdS)z\Check a JSON Schema property and add param_name to array_params/object_params if applicable.typearrayNranyOfoneOf)r(add)rrrr schema_typevariant variant_types r+rrs**V$$Kg$$$h*%%%::gr**VZZ-D-DD{{6** 7 " "   Z ( ( ( FF 8 # #   j ) ) ) FF $ r*rcv|D]}||}t|trm tj|}t|t r&i|||i}t d|d}#tjtf$rYwxYw|D]}||}t|trm tj|}t|tr&i|||i}t d|d}#tjtf$rYwxYw|S)zAuto-coerce string-encoded JSON arrays/objects to native types. LLM agents frequently serialize list and dict tool arguments as JSON strings. This is backward-compatible: native arrays/objects pass through unchanged. z&Coerced string to list for parameter ''z&Coerced string to dict for parameter ') r( isinstancestrjsonloadslistr_rJSONDecodeError TypeErrordict)rrrrvalparseds r+rrs| #   mmJ'' c3    Cfd++Y A9 Aj& A AILL!W*!W!W!WXXX()4      $   mmJ'' c3    Cfd++Y A9 Aj& A AILL!W*!W!W!WXXX()4       s%ABBB ADD54D5c eZdZdZ ddedefdZdeded edzfd Zd Z d Z dd e dedeeefdzfdZ dS) MCPMiddlewareu.ASGI middleware that intercepts MCP requests and routes to appropriate MCP server. This middleware wraps the main FastAPI app and intercepts requests matching the configured prefix (default: /mcp). Non-MCP requests pass through to the inner app. Authentication: 1. If HINDSIGHT_API_MCP_AUTH_TOKEN is set (legacy), validates against that token 2. Otherwise, uses TenantExtension.authenticate_mcp() from the MemoryEngine - DefaultTenantExtension: no auth required (local dev) - ApiKeyTenantExtension: validates against env var Two modes based on URL structure: 1. Multi-bank mode (for /mcp/ root endpoint): - Exposes all tools: retain, recall, reflect, list_banks, create_bank - All tools include optional bank_id parameter for cross-bank operations - Bank ID from: X-Bank-Id header or HINDSIGHT_MCP_BANK_ID env var 2. Single-bank mode (for /mcp/{bank_id}/ endpoints): - Exposes bank-scoped tools only: retain, recall, reflect - No bank_id parameter (comes from URL) - No bank management tools (list_banks, create_bank) - Recommended for agent isolation Bank ID resolution priority: 1. URL path (e.g., /mcp/{bank_id}/) → single-bank mode 2. X-Bank-Id header → multi-bank mode 3. HINDSIGHT_MCP_BANK_ID env var → multi-bank mode (default: "default") Examples: # Single-bank mode (recommended for agent isolation) claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/ \ --header "Authorization: Bearer " # Multi-bank mode (for cross-bank operations) claude mcp add --transport http hindsight http://localhost:8888/mcp \ --header "X-Bank-Id: my-bank" --header "Authorization: Bearer " /mcpNr6prefixc||_||_||_|j|_|r |r||_||_||_||_dSt}|j } t|d|_|j d| |_t|d|_|j d| |_dS)NTr7/pathstateless_httpF) apprr6_tenant_extensiontenant_extensionmulti_bank_appsingle_bank_appmulti_bank_serversingle_bank_serverr mcp_statelessrkhttp_app) selfrr6rrrrrre statelesss r+__init__zMCPMiddleware.__init__As  & 8  ho h"0D #2D %6D "&8D # # #,--M%3I%6v$%O%O%OD ""&"8"A"As[d"A"e"eD &75&Q&Q&QD ##'#:#C#C]f#C#g#gD r*scoperr&c|}|dgD]3\}}||kr|cS4dS)z'Extract a header value from ASGI scope.headersN)lowerencoder(decode)rrr name_lower header_name header_values r+ _get_headerzMCPMiddleware._get_header_svZZ\\((** ).9b)A)A - - %K  ""j00#**,,,,,1tr*cj K|ddkr|||d{VdS|dd}||jks<||jdzs|||d{VdS|dd}|dkrO||d}|s7t d |d{VdS|t|jdpd}||d }d}|rE|d r|d d n| }d} d} d} d } trP|s| ddd{VdS|tkr| ddd{VdSd} d} n t|} |j | d{V} | j} | j} nI#t"$r<}| dt%||jd{VYd}~dSd}~wwxYw| r | jrt+j| jnd}dd |}|drct|dkrP|dddd}|dr*|ddt|dkr d|dznd}s||ds$t0t dr|jn|j}t6}|rt8|nd}| rt:| nd}| rt<| nd}t>| } | }||d<d|d<||d}|rd|vr:d|dgD}|!d||d<d fd}||||d{Vt6"||t8"||t:"||t<"|t>"||t+j"|dSdS#t6"||t8"||t:"||t<"|t>"||t+j"|wwxYw)NrhttprrmethodGETzMcp-Session-Idu>MCP GET without session ID (client probe) — returning 200 OK AuthorizationzBearer FizAuthorization header requiredzInvalid authentication tokenT)api_key) extra_headersrqrz X-Bank-IdzUsing default bank_id: root_pathacceptztext/event-streamcLg|]!\}}|dk||f"S)accept)rrus r+ z*MCPMiddleware.__call__..s3eeedaaggii[dNdNdAq6NdNdNdr*r)rs#application/json, text/event-streamcZK|ddkr*|dgD]\}}|dkrd|vrdn|ddkrTrRrP|dd }|r8d |vr4|d d d }i|d|i}|d{VdS)Nrhttp.response.startr content-typestext/event-streamThttp.response.bodybodyr*s /messagessdata: /messageszdata: /z /messages)r(replacer)messagerrrbank_idbank_id_from_pathis_sse_responsesends r+ send_wrapperz,MCPMiddleware.__call__..send_wrappers6?&;;;5<[[B5O5O""1 \&/99>RVb>b>b.2O!E6?&:::?P:Ud:";;vs33D<  4 4#||,>@\'@\@\@\@c@c@e@eff";W";fd";";d7mm#########r*)#rr(rrsrr_r_send_oklenstripMCP_AUTH_TOKEN _send_errorrrauthenticate_mcp tenant_id api_key_idr rr schema_namerrrtDEFAULT_BANK_IDrrrrr!r#r%copyappendreset)rrreceiverrr session_id auth_header auth_tokentenant_contextauth_tenant_idauth_api_key_idmcp_pre_authenticated auth_contextr schema_tokennew_pathparts target_app bank_id_token api_key_tokentenant_id_tokenapi_key_id_tokenmcp_auth_token new_scope accept_headerrrrrrs ` @@@r+__call__zMCPMiddleware.__call__gs =F " "((5'400 0 0 0 0 0 0 0 Fyy$$ ##tt{S7H'I'I#((5'400 0 0 0 0 0 0 0 F 8R(( U??))%1ABBJ  ]^^^mmD)))))))))C $$&&'.3&&uo>> !%  o4?4J4J94U4UnQRR..000[f[l[l[n[nJ%)&* %   &&tS2QRRRRRRRRR^++&&tS2PQQQQQQQQQ!N$( ! ! -jAAA '+'<'M'Ml'['[![![![![![![!-!7"."9&   &&tS#a&& &RRRRRRRRR  @N vR`Rl vO  : ; ; ;rv ! ??3   ECIIMMHNN3**EQx E($(!-0ZZ!^^3q>> ;&&uk::G >%G LL<7<< = = = .?WT))DDW ),,W55 > > > > > > > >  " "= 1 1 1( &&}555*"((999+#))*:;;; & , ,^ < < <'%l33333('  " "= 1 1 1( &&}555*"((999+#))*:;;; & , ,^ < < <'%l3333(s&>H I 1IIBTB!V2c^K|dddgdd{V|dddd{VdS) zMSend a 200 OK response with empty body (used for GET probes without session).rrsapplication/jsonrstatusrNrs{}rrr))rrs r+rzMCPMiddleware._send_oksd-BC           d,             r*rrrc`Ktjd|i}dg}|piD]@\}}|||fA|d||dd{V|d|dd{VdS)zSend an error response.rrrrNrr)rdumpsrr}r) rrrrrrrkeyvalues r+rzMCPMiddleware._send_errorsz7G,--44669:(.B5577 ; ;JC NNCJJLL%,,..9 : : : :d- "           d,             r*)rNNNN)N) ra __module__ __qualname____doc__rrrrrrrintrr)r*r+rrs%%Vhhh hhhh<SS4ZW4W4W4r     c C PTUXZ]U]P^aePe      r*rct}|j}t|d}|d|}t|d}|d|}td|d||||fS)a+Create multi-bank and single-bank MCP servers and their Starlette apps. Returns the servers and apps separately so lifespans can be chained before the middleware wraps the main app. Returns: Tuple of (multi_bank_server, single_bank_server, multi_bank_app, single_bank_app) TrrrFz$MCP servers created (stateless_http=))rrrkrr_r)r6rerrrrrs r+create_mcp_serversr%s$%%M+I)&TBBB&//S/SSN*6eDDD(11s91UUO KKCyCCCDDD 0./ QQr*)T)Arrloggingos contextvarsrfastmcpr hindsight_apirrr\hindsight_api.configr"hindsight_api.engine.memory_enginerhindsight_api.extensionsr r hindsight_api.extensions.tenantr hindsight_api.mcp_toolsr r rhindsight_api.modelsrenvironr(r_log_level_strCRITICALERRORWARNINGINFODEBUG_log_level_map basicConfig getLoggerrar_rrrr__annotations__rr!r#r%boolr,r/r1r3r5rkrrrcrrrrrr)r*r+r7sIII  """"""&&&&&&::::::000000>>>>>>AAAAAAAA??????RRRRRRRRRR////// 96BBHHJJ ] L ] ]    ^W\ : : A  8 $ $*..!8)DD >??,6:6GQU+V+V+V*S4Z(VVV,6:6GQU+V+V+V*S4Z(VVV.8Z8KUY-Z-Z-ZJsTz*ZZZ.8j9MW[.\.\.\Zd +\\\0:z:U_d/e/e/eJt,eee"S4Z"""" "S4Z"""" $sTz$$$$ %d %%%% ,t,,,, LLlLLLLLL^  D     1Qg1Q$1Q1Q1Q1QhTs#c(cfgjckpt,4s3xPSTWPX]a>I I I I I I I I XR|RRRRRRr*