MCP Server
The MCP (Model Context Protocol) server module enables AI assistants to interact with Kumiho Cloud.
For usage documentation, see MCP Server Integration.
Kumiho MCP Server - Model Context Protocol integration for Kumiho Cloud.
This module provides an MCP (Model Context Protocol) server that exposes Kumiho Cloud functionality to AI assistants like GitHub Copilot, Claude, and other MCP-compatible clients.
The server enables AI assistants to: - Query and navigate asset graphs - Analyze dependencies and impact - Search for items across projects - Track AI lineage and provenance - Manage revisions and artifacts
- Usage:
Run as a standalone server:
python -m kumiho.mcp_server
Or use the CLI entry point:
kumiho-mcp
- Configuration:
The MCP server uses the same authentication as the Kumiho SDK. Run
kumiho-auth loginfirst to cache credentials.- Environment Variables:
KUMIHO_MCP_LOG_LEVEL: Log level (DEBUG, INFO, WARNING, ERROR). Default: INFO KUMIHO_MCP_TOOL_PROFILE: Which tool surface to expose — “full” (default,
every tool) or “connector” (the curated hosted set). Overridden by an explicit
profileargument tocreate_mcp_server().- KUMIHO_MCP_HOSTED: Set to “1” when this process serves many tenants. Stops
the server touching process-global user state — no
os.environwrites, no~/.kumihoreads, no local artifact files — and makes every cache tenant-scoped. Seekumiho.request_context.
Example MCP client configuration (VS Code settings.json):
{
"mcp": {
"servers": {
"kumiho": {
"command": "kumiho-mcp"
}
}
}
}
- kumiho.mcp_server.tool_get_spaces(project_name, recursive=False)[source]
Get spaces within a project.
- kumiho.mcp_server.tool_search_items(context_filter='', name_filter='', kind_filter='', include_metadata=False, auth_token='')[source]
Search for items across projects and spaces.
- kumiho.mcp_server.tool_fulltext_search(query, context='', kind='', include_deprecated=False, include_revision_metadata=False, include_artifact_metadata=False, include_metadata=False, limit=20, auth_token='')[source]
Full-text fuzzy search across items (Google-like search).
For STUDIO+ tiers with vector embeddings enabled, uses hybrid search (fulltext + vector similarity) for improved accuracy when searching revision metadata.
- kumiho.mcp_server.tool_memory_store(project='CognitiveMemory', space_path='', space_hint='', policy_kref=None, memory_item_kind='conversation', bundle_name='', memory_type='summary', title='', summary='', user_text='', assistant_text='', artifact_location='', artifact_name='chat_io', tags=None, source_revision_krefs=None, metadata=None, edge_type='DERIVED_FROM', stack_revisions=True)[source]
Store a memory bundle with minimal inputs.
When stack_revisions is True (the default), searches for an existing item in the same space with similar content and stacks a new revision on it instead of creating a duplicate item. Falls back to creating a new item when no similar item is found or the search fails.
- Return type:
- Parameters:
- kumiho.mcp_server.tool_memory_store_batch(captures, project='CognitiveMemory', space_path='', memory_item_kind='conversation', source_revision_krefs=None, edge_type='DERIVED_FROM', stack_revisions=True, idempotency_prefix='')[source]
Bulk counterpart of
tool_memory_store()— N captures, one batched write.Collapses the per-capture
create_item+create_revision+ auto-artifact into a singlebatch_create_revisionstransaction. This is what backfill and any other high-volume, multi-capture write should use: it removes the neo4j relationship-group deadlock that naive per-capture concurrency triggers, and cuts the heaviest writes from ~2N RPCs to one. Per-capture credential screening, space resolution, fuzzy-stack decision, tagging, bundling and DERIVED_FROM edges are preserved exactly — the server has no batch RPC for tag/bundle/edge, so those remain per-item (still far lighter than the create/revision writes the batch collapses).- Return type:
- Parameters:
- Each capture dict mirrors the fields reflect passes to
tool_memory_store: type,title,content— the memory itself.tags— optional; defaults to["published"].metadata— optional pre-validated dict (e.g.{"event_date": ...}).space_hint— optional per-capture space override.
Returns
{"results": [per-capture dict | {"error": ...}], "stored_krefs": [...], "stacked": <int>}—resultsis positional (one entry per input capture,Nonecollapses to anerrorentry). Each successful entry carriesstack_score, the best similarity score the stacking search saw, reported whether or not it stacked.
- kumiho.mcp_server.tool_memory_retrieve(project='CognitiveMemory', query='', keywords=None, topics=None, space_paths=None, bundle_names=None, memory_item_kind='conversation', limit=5, mode='search', include_revision_metadata=True, unroll_revisions=False, memory_types=None)[source]
Retrieve memory krefs using fuzzy search with bundle and fallback support.
Uses Google-like fuzzy search (kumiho.search) as the primary method for natural language queries. Falls back to pattern matching for specific modes or when fuzzy search returns no results.
- Parameters:
- Return type:
- kumiho.mcp_server.tool_get_dependencies(revision_kref, max_depth=5, edge_types=None)[source]
Get all dependencies of a revision (what it depends on).
- kumiho.mcp_server.tool_get_dependents(revision_kref, max_depth=5, edge_types=None)[source]
Get all dependents of a revision (what depends on it).
- kumiho.mcp_server.tool_get_provenance_summary(revision_kref, max_depth=10)[source]
Get provenance summary with AI metadata.
- kumiho.mcp_server.tool_analyze_impact(revision_kref, max_depth=10, edge_types=None)[source]
Analyze the impact of changes to a revision.
- kumiho.mcp_server.tool_find_path(source_kref, target_kref, max_depth=10, edge_types=None)[source]
Find the shortest path between two revisions.
- kumiho.mcp_server.tool_get_edges(revision_kref, direction='both', edge_type=None)[source]
Get edges for a revision.
- kumiho.mcp_server.tool_get_artifacts_by_location(location)[source]
Find all artifacts at a specific file location (reverse lookup).
- kumiho.mcp_server.tool_get_item_revisions(item_kref, include_metadata=False)[source]
Get all revisions for an item.
- kumiho.mcp_server.tool_get_revision_by_tag(item_kref, tag)[source]
Get a revision by tag (e.g., ‘latest’, ‘published’, ‘approved’).
- kumiho.mcp_server.tool_get_revision_as_of(item_kref, tag, time)[source]
Get the revision that had a specific tag at a given point in time.
This enables time-travel queries for reproducible builds and historical analysis. For example: “What was the published revision on June 1st, 2025?”
- kumiho.mcp_server.tool_batch_get_revisions(revision_krefs=None, item_krefs=None, tag='latest', allow_partial=True)[source]
Batch-fetch multiple revisions in a single call.
Supports two modes: - Direct revision krefs: provide
revision_krefsto fetch specific revisions. - Item krefs + tag: provideitem_krefsand atagto resolvethat tag (e.g. ‘latest’, ‘published’) for each item.
Returns found revisions and a list of krefs that could not be resolved.
- kumiho.mcp_server.tool_create_revision(item_kref, metadata=None)[source]
Create a new revision for an item.
- kumiho.mcp_server.tool_create_edge(source_kref, target_kref, edge_type, metadata=None)[source]
Create an edge between two revisions.
- kumiho.mcp_server.tool_create_project(name, description='', allow_public=False)[source]
Create a new Kumiho project.
- kumiho.mcp_server.tool_create_space(project_name, space_name, parent_path=None)[source]
Create a new space within a project.
- kumiho.mcp_server.tool_create_item(space_path, item_name, kind, metadata=None)[source]
Create a new item within a space.
- kumiho.mcp_server.tool_create_artifact(revision_kref, name, location)[source]
Create an artifact for a revision.
- kumiho.mcp_server.tool_create_bundle(space_path, bundle_name, metadata=None)[source]
Create a new bundle within a space.
- kumiho.mcp_server.tool_delete_project(project_name, force=False, impact_snapshot_id='', impact_snapshot_hash='', confirmed=False)[source]
Archive a Project, or perform a two-step snapshot-gated hard-delete.
- kumiho.mcp_server.tool_delete_edge(source_kref, target_kref, edge_type)[source]
Delete an edge between two revisions.
- kumiho.mcp_server.tool_deprecate_item(item_kref, deprecated=True)[source]
Set the deprecated status of an item.
- kumiho.mcp_server.tool_remove_bundle_member(bundle_kref, item_kref)[source]
Remove an item from a bundle.
- kumiho.mcp_server.CONNECTOR_PROFILE_TOOLS: Tuple[str, ...] = ('kumiho_memory_engage', 'kumiho_memory_recall', 'kumiho_memory_retrieve', 'kumiho_memory_space_profile', 'kumiho_chat_get', 'kumiho_search_items', 'kumiho_get_item', 'kumiho_get_revision_by_tag', 'kumiho_list_projects', 'kumiho_get_spaces', 'kumiho_get_provenance_summary', 'kumiho_memory_reflect', 'kumiho_memory_store', 'kumiho_memory_consolidate', 'kumiho_memory_decompose', 'kumiho_create_space', 'kumiho_deprecate_item', 'kumiho_chat_clear')
The hosted connector’s curated surface (connector plan §2.2, less
kumiho_memory_dream_state). Ordered read / additive-write / destructive, which is also the order the directory listing presents them in.kumiho_memory_dream_stateis in the plan’s table but is deliberately not here for v1. Its assessment pass needs an LLM key and hosted tenants are keyless (plan §1.10), so listing it would publish a tool that fails at call time — which directory review catches head-on, since it asks the submitter to confirm every listed tool has been run. It keeps itsTOOL_ANNOTATIONSentry, so the full profile is unaffected; re-add the name here once per-tenant LLM metering exists.
- kumiho.mcp_server.TOOL_PROFILES: Tuple[str, ...] = ('full', 'connector')
Every accepted value of the
profileargument /KUMIHO_MCP_TOOL_PROFILE.
- exception kumiho.mcp_server.ToolNotInProfileError[source]
Bases:
ExceptionA tool exists, but the active profile does not offer it.
Raised rather than returned, so the refusal reaches the client as a real MCP tool error (
isError: true) instead of a successful result whose text happens to contain the word “error”. Clients and models branch onisError; a refusal that reports success reads as “the call went through”, which is the opposite of what happened.mcp 1.x turns an exception out of the
call_toolhandler into an error result carryingstr(exc); the 2.x branch catches this type explicitly and builds the same result. One raise, one message, both majors.
- kumiho.mcp_server.resolve_tool_profile(profile=None)[source]
Normalize an explicit profile, falling back to the environment.
Nonemeans “unspecified”, not “full”: it defers toKUMIHO_MCP_TOOL_PROFILEso a deployment can pick the profile without touching the code that constructs the server. An empty or whitespace-only value on either path means full, which keepsKUMIHO_MCP_TOOL_PROFILE=from being a silent misconfiguration.
- kumiho.mcp_server.profile_tool_names(profile)[source]
The names profile admits, or
Nonefor “everything in TOOLS”.
- kumiho.mcp_server.tools_for_profile(profile)[source]
The
TOOLSentries profile exposes.Read from
TOOLSon every call rather than snapshotted at server construction.TOOLSis a module-level list that kumiho-memory extends at import time — with a further two extensions gated behind env flags — so a snapshot would silently depend on import order, and a filter built from one would go stale.
- kumiho.mcp_server.create_mcp_server(profile=None, instructions=None)[source]
Create and configure the Kumiho MCP server.
The six handlers are defined once, in the shapes mcp 1.x expects, and are either registered through the 1.x decorators or wrapped into the
(ctx, params) -> ResultModelshape mcp 2.0 wants. Keeping one copy of each body is what stops the two branches from drifting apart.- Parameters:
profile (
Optional[str]) – Which tool surface to expose.Nonedefers toKUMIHO_MCP_TOOL_PROFILEand then to"full"— today’s whole tool list, which is what the stdio plugin gets."connector"exposes the curated hosted set (CONNECTOR_PROFILE_TOOLS). An unrecognized name raisesValueErrorrather than silently serving everything: a typo in a deployment’s env would otherwise publish every destructive tool to a public connector.instructions (
Optional[str]) – Server instructions returned in the MCPinitializeresult. Defaults toCONNECTOR_INSTRUCTIONSfor the connector profile and to nothing otherwise, because the stdio plugin already carries the protocol as a skill and a second copy would just spend the user’s context twice.
- Return type:
Server
Nothing here starts the orphan watchdog or otherwise assumes a stdio child process — that belongs to
main(). A hosted server builds many of these inside a long-lived web process, where a watchdog would watch the wrong parent andos._exitthe whole service.
- kumiho.mcp_server.main()[source]
Entry point for the MCP server CLI.
Ends with
os._exit: once the stdio transport is gone there is nothing left for this process to do, and lingering non-daemon threads (thread pools, gRPC channels) must never keep a dead server alive — orphaned servers accumulate across client restarts (kumiho-plugins#25).- Return type:
Tool Definitions
The MCP server exposes 39 tools for interacting with Kumiho Cloud:
Read Operations:
kumiho_list_projects- List all accessible projectskumiho_get_project- Get project by namekumiho_get_spaces- Get spaces in a projectkumiho_get_space- Get a space by pathkumiho_get_item- Get item by krefkumiho_search_items- Search items with filterskumiho_get_item_revisions- Get all revisions for an itemkumiho_get_revision- Get revision by krefkumiho_get_revision_by_tag- Get revision by tagkumiho_get_artifacts- Get artifacts for a revisionkumiho_get_artifact- Get artifact by krefkumiho_get_bundle- Get bundle by krefkumiho_resolve_kref- Resolve kref to file locationkumiho_get_artifacts_by_location- Reverse lookup by file path
Graph Operations:
kumiho_get_dependencies- Get what a revision depends onkumiho_get_dependents- Get what depends on a revisionkumiho_analyze_impact- Analyze downstream impactkumiho_find_path- Find path between revisionskumiho_get_edges- Get edges for a revision
Create Operations:
kumiho_create_project- Create a new projectkumiho_create_space- Create a spacekumiho_create_item- Create an itemkumiho_create_revision- Create a revisionkumiho_create_artifact- Create an artifactkumiho_create_bundle- Create a bundlekumiho_create_edge- Create a relationshipkumiho_tag_revision- Tag a revision
Delete Operations:
kumiho_delete_project- Delete a projectkumiho_delete_space- Delete a spacekumiho_delete_item- Delete an itemkumiho_delete_revision- Delete a revisionkumiho_delete_artifact- Delete an artifactkumiho_delete_edge- Delete a relationship
Update Operations:
kumiho_untag_revision- Remove a tagkumiho_set_metadata- Set metadatakumiho_deprecate_item- Deprecate an itemkumiho_add_bundle_member- Add item to bundlekumiho_remove_bundle_member- Remove item from bundlekumiho_get_bundle_members- List bundle members