Axom MCP Server

Instructions

Implementation Reference

• src/axom_mcp/handlers/discover.py:45-76 (handler)

  Main handler function that processes axom_mcp_discover tool calls. Validates input using DiscoverInput schema, then dispatches to appropriate discovery domain handlers (files, tools, memory, capabilities, or all). Returns JSON string with results.
  async def handle_discover(arguments: Dict[str, Any]) -> str: """Handle axom_mcp_discover tool calls. Args: arguments: Tool arguments containing domain and parameters Returns: JSON string with discovery result """ # Validate input input_data = DiscoverInput(**arguments) domain = input_data.domain filter_criteria = input_data.filter or {} limit = input_data.limit or 100 recursive = input_data.recursive if input_data.recursive is not None else True try: if domain == "files": return await _discover_files(filter_criteria, limit, recursive) elif domain == "tools": return await _discover_tools() elif domain == "memory": return await _discover_memory(limit) elif domain == "capabilities": return await _discover_capabilities() elif domain == "all": return await _discover_all(filter_criteria, limit, recursive) else: return json.dumps({"error": f"Unknown domain: {domain}"}) except Exception as e: logger.error(f"Discovery failed: {e}") return json.dumps({"error": str(e)})
• src/axom_mcp/handlers/discover.py:79-153 (handler)

  Helper function _discover_files that implements file system discovery. Supports pattern matching, file/directory filtering, recursive/non-recursive traversal, and returns file metadata including name, path, type, and size.
  async def _discover_files( filter_criteria: Dict[str, Any], limit: int, recursive: bool ) -> str: """Discover files in allowed directories.""" results = [] pattern = filter_criteria.get("pattern", "*") file_type = filter_criteria.get("type", "all") # file, directory, all base_path = filter_criteria.get("path", os.getcwd()) try: base = _validate_path(base_path) except ValueError: base = Path(os.getcwd()).resolve() if not base.exists(): return json.dumps({"error": f"Path not found: {base_path}"}) def should_include(path: Path) -> bool: """Check if path matches filter criteria.""" # Check pattern if not fnmatch.fnmatch(path.name, pattern): return False # Check type if file_type == "file" and not path.is_file(): return False if file_type == "directory" and not path.is_dir(): return False return True try: if recursive: for path in base.rglob("*"): if len(results) >= limit: break if should_include(path): results.append( { "name": path.name, "path": str(path), "relative_path": str(path.relative_to(base)), "type": "file" if path.is_file() else "directory", "size": path.stat().st_size if path.is_file() else None, } ) else: for path in base.iterdir(): if len(results) >= limit: break if should_include(path): results.append( { "name": path.name, "path": str(path), "relative_path": str(path.relative_to(base)), "type": "file" if path.is_file() else "directory", "size": path.stat().st_size if path.is_file() else None, } ) except PermissionError: pass # Skip directories we can't access # Sort results for deterministic output results.sort(key=lambda x: (x["type"], x["name"])) return json.dumps( { "success": True, "domain": "files", "base_path": str(base), "count": len(results), "results": results, } )
• src/axom_mcp/handlers/discover.py:156-303 (handler)

  Helper function _discover_tools that returns metadata about all available MCP tools. Includes axom_mcp_memory, axom_mcp_exec, axom_mcp_analyze, axom_mcp_discover, and axom_mcp_transform with their parameters and capabilities.
  async def _discover_tools() -> str: """Discover available MCP tools.""" tools = [ { "name": "axom_mcp_memory", "description": "Store, retrieve, search, and manage persistent memories in the Axom database", "actions": ["read", "write", "list", "search", "delete"], "parameters": { "action": { "type": "string", "required": True, "enum": ["read", "write", "list", "search", "delete"], }, "name": { "type": "string", "required": False, "description": "Memory identifier", }, "content": { "type": "string", "required": False, "description": "Memory content", }, "query": { "type": "string", "required": False, "description": "Search query", }, "memory_type": { "type": "string", "enum": ["long_term", "short_term", "reflex", "dreams"], }, "importance": { "type": "string", "enum": ["critical", "important", "normal", "low"], }, "tags": {"type": "array", "items": {"type": "string"}}, "limit": {"type": "integer", "default": 50}, }, }, { "name": "axom_mcp_exec", "description": "Execute file operations and shell commands with chain-reaction support", "operations": ["read", "write", "shell"], "parameters": { "operation": { "type": "string", "required": True, "enum": ["read", "write", "shell"], }, "target": { "type": "string", "required": True, "description": "File path or command", }, "data": { "type": "string", "required": False, "description": "Data to write", }, "chain": { "type": "array", "description": "Chain of subsequent operations", }, }, }, { "name": "axom_mcp_analyze", "description": "Analyze code and data with configurable depth and scope", "types": ["debug", "review", "audit", "refactor", "test"], "parameters": { "type": { "type": "string", "required": True, "enum": ["debug", "review", "audit", "refactor", "test"], }, "target": { "type": "string", "required": True, "description": "File path or code to analyze", }, "focus": { "type": "string", "description": "Focus area (e.g., security, performance)", }, "depth": { "type": "string", "enum": ["minimal", "low", "medium", "high", "max"], "default": "medium", }, "output_format": { "type": "string", "enum": ["summary", "detailed", "actionable"], "default": "summary", }, }, }, { "name": "axom_mcp_discover", "description": "Discover available resources, structures, and capabilities", "domains": ["files", "tools", "memory", "capabilities", "all"], "parameters": { "domain": { "type": "string", "required": True, "enum": ["files", "tools", "memory", "capabilities", "all"], }, "filter": {"type": "object", "description": "Filter criteria"}, "limit": {"type": "integer", "default": 100}, "recursive": {"type": "boolean", "default": True}, }, }, { "name": "axom_mcp_transform", "description": "Transform data between formats and structures", "formats": ["json", "yaml", "csv", "markdown", "code"], "parameters": { "input": { "type": "string", "required": True, "description": "Input data to transform", }, "input_format": { "type": "string", "enum": ["json", "yaml", "csv", "markdown", "code"], }, "output_format": { "type": "string", "required": True, "enum": ["json", "yaml", "csv", "markdown", "code"], }, "rules": {"type": "array", "description": "Transformation rules"}, "template": { "type": "string", "description": "Template for transformation", }, }, }, ] return json.dumps( { "success": True, "domain": "tools", "count": len(tools), "results": tools, } )
• src/axom_mcp/schemas.py:266-285 (schema)

  DiscoverInput schema class defining input validation for axom_mcp_discover tool. Specifies required 'domain' field with enum values (files, tools, memory, capabilities, all), optional filter, limit (1-1000), recursive flag, and chain parameter.
  class DiscoverInput(BaseModel): """Input schema for axom_mcp_discover tool.""" model_config = {"extra": "forbid"} domain: str = Field( ..., pattern="^(files|tools|memory|capabilities|all)$", description="Discovery domain", ) filter: Optional[Dict[str, Any]] = Field( default=None, description="Filter criteria (pattern, type, etc.)" ) limit: Optional[int] = Field( default=None, ge=1, le=1000, description="Maximum results" ) recursive: Optional[bool] = Field(default=None, description="Recursive discovery") chain: Optional[List[Dict[str, Any]]] = Field( default=None, max_length=10, description="Chain operations based on discovery" )
• src/axom_mcp/server.py:284-328 (registration)

  Tool registration for axom_mcp_discover in the TOOLS list. Defines tool name, comprehensive description with discovery domains and filter options, and input schema with domain, filter, limit, recursive, and chain parameters. Dispatched via handle_discover at line 497.
  Tool( name="axom_mcp_discover", description="""Discover available resources, structures, and capabilities. Discovery Domains: - files: List and search files in allowed directories - tools: List available MCP tools and their capabilities - memory: Explore memory structure and statistics - capabilities: Check server capabilities and configuration - all: Comprehensive discovery across all domains Filter Options: - pattern: Glob pattern for file filtering (e.g., *.py) - type: File type filter (file, directory, all) - memory_type: Filter memories by type - importance: Filter memories by importance Chain Support: Use chain parameter to act on discovered resources.""", inputSchema={ "type": "object", "properties": { "domain": { "type": "string", "enum": ["files", "tools", "memory", "capabilities", "all"], "description": "Discovery domain", }, "filter": {"type": "object", "description": "Filter criteria"}, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum results", }, "recursive": {"type": "boolean", "description": "Recursive discovery"}, "chain": { "type": "array", "items": {"type": "object"}, "description": "Chain operations based on discovery", }, }, "required": ["domain"], }, annotations=TOOL_ANNOTATIONS["discover"], ),