hive/core/MCP_SERVER_GUIDE.md

MCP Server Guide - Agent Building Tools

Note: This document is stale. The previous coder-tools MCP server has been replaced by files-tools (tools/files_server.py), which only exposes file I/O (read_file, write_file, edit_file, hashline_edit, search_files). The agent-building, shell, and snapshot tools that used to live here have been removed.

This guide covers the MCP tools available for building goal-driven agents.

Setup

Quick Setup

# Run the quickstart script (recommended)
./quickstart.sh

Manual Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "files-tools": {
      "command": "uv",
      "args": ["run", "files_server.py", "--stdio"],
      "cwd": "/path/to/hive/tools"
    }
  }
}

Available MCP Tools

Session Management

create_session

Create a new agent building session.

Parameters:

• name (string, required): Name of the agent

Example:

{
  "name": "research-summary-agent"
}

get_session_status

Get the current status of the build session.

Returns:

• Session name
• Goal status
• Number of nodes
• Number of edges
• Validation status

---

Goal Definition

set_goal

Define the goal for the agent with success criteria and constraints.

Parameters:

• goal_id (string, required): Unique identifier for the goal
• name (string, required): Human-readable name
• description (string, required): What the agent should accomplish
• success_criteria (string, required): JSON array of success criteria
• constraints (string, optional): JSON array of constraints

Success Criterion Structure:

{
  "id": "criterion_id",
  "description": "What should be achieved",
  "metric": "How to measure it",
  "target": "Target value",
  "weight": 1.0
}

Constraint Structure:

{
  "id": "constraint_id",
  "description": "What must not happen",
  "constraint_type": "hard|soft",
  "category": "safety|quality|performance"
}

---

Node Management

add_node

Add a processing node to the agent graph.

Parameters:

• node_id (string, required): Unique node identifier
• name (string, required): Human-readable name
• description (string, required): What this node does
• node_type (string, required): Must be event_loop (the only valid type)
• input_keys (string, required): JSON array of input variable names
• output_keys (string, required): JSON array of output variable names
• system_prompt (string, optional): System prompt for the LLM
• tools (string, optional): JSON array of tool names
• client_facing (boolean, optional): Set to true for human-in-the-loop interaction

Node Type:

event_loop: LLM-powered node with self-correction loop

• Requires: system_prompt
• Optional: tools (array of tool names, e.g., ["web_search", "web_fetch"])
• Optional: client_facing (set to true for HITL / user interaction)
• Supports: iterative refinement, judge-based evaluation, tool use, streaming

Example:

{
  "node_id": "search_sources",
  "name": "Search Sources",
  "description": "Searches for relevant sources on the topic",
  "node_type": "event_loop",
  "input_keys": "[\"topic\", \"search_queries\"]",
  "output_keys": "[\"sources\", \"source_count\"]",
  "system_prompt": "Search for sources using the provided queries...",
  "tools": "[\"web_search\"]"
}

---

Edge Management

add_edge

Connect two nodes with an edge to define execution flow.

Parameters:

• edge_id (string, required): Unique edge identifier
• source (string, required): Source node ID
• target (string, required): Target node ID
• condition (string, optional): When to traverse: on_success (default) or on_failure
• condition_expr (string, optional): Python expression for conditional routing
• priority (integer, optional): Edge priority (default: 0)

Example:

{
  "edge_id": "search_to_extract",
  "source": "search_sources",
  "target": "extract_content",
  "condition": "on_success"
}

---

Graph Validation

validate_graph

Validate the complete graph structure.

Checks:

• Entry node exists
• All nodes are reachable from entry
• Terminal nodes have no outgoing edges
• No cycles (unless explicitly allowed)
• Context flow: all required inputs are available

Returns:

• valid (boolean)
• errors (array): List of validation errors
• warnings (array): Non-critical issues
• entry_node (string): Entry node ID
• terminal_nodes (array): Terminal node IDs

---

Graph Export

export_graph

Export the validated graph as an agent specification.

What it does:

1. Validates the graph
2. Validates edge connectivity
3. Writes files to disk:
   • exports/{agent-name}/agent.json - Full agent specification
   • exports/{agent-name}/README.md - Auto-generated documentation

Returns:

• success (boolean)
• files_written (object): Paths and sizes of written files
• agent (object): Agent metadata
• graph (object): Graph specification
• goal (object): Goal definition
• required_tools (array): All tools used by the agent

Important: This tool automatically writes files to the exports/ directory!

---

Testing

test_node

Test a single node with sample inputs.

Parameters:

• node_id (string, required): Node to test
• test_input (string, required): JSON object with input values
• mock_llm_response (string, optional): Mock LLM response for testing

Example:

{
  "node_id": "research_planner",
  "test_input": "{\"topic\": \"LLM compaction\"}"
}

test_graph

Test the complete agent graph with sample inputs.

Parameters:

• test_input (string, required): JSON object with initial inputs
• dry_run (boolean, optional): Simulate without LLM calls (default: true)
• max_steps (integer, optional): Maximum execution steps (default: 10)

Example:

{
  "test_input": "{\"topic\": \"AI safety\"}",
  "dry_run": true,
  "max_steps": 10
}

---

Example Workflow

Here's a complete workflow for building a research agent:

# 1. Create session
create_session(name="research-agent")

# 2. Define goal
set_goal(
    goal_id="research-goal",
    name="Research Topic Agent",
    description="Research a topic and produce a summary",
    success_criteria=json.dumps([{
        "id": "comprehensive",
        "description": "Cover main aspects",
        "metric": "Key topics addressed",
        "target": "At least 3-5 aspects",
        "weight": 1.0
    }])
)

# 3. Add nodes
add_node(
    node_id="planner",
    name="Research Planner",
    description="Creates research strategy",
    node_type="event_loop",
    input_keys='["topic"]',
    output_keys='["strategy", "queries"]',
    system_prompt="Analyze topic and create research plan..."
)

add_node(
    node_id="searcher",
    name="Search Sources",
    description="Find relevant sources",
    node_type="event_loop",
    input_keys='["queries"]',
    output_keys='["sources"]',
    system_prompt="Search for sources...",
    tools='["web_search"]'
)

# 4. Connect nodes
add_edge(
    edge_id="plan_to_search",
    source="planner",
    target="searcher"
)

# 5. Validate
validate_graph()

# 6. Export
export_graph()

The exported agent will be saved to exports/research-agent/.

---

Tips

1. Start with the goal: Define clear success criteria before building nodes
2. Test nodes individually: Use test_node to verify each node works
3. Use conditional edges for branching: Define condition_expr on edges for decision points
4. Validate early, validate often: Run validate_graph after adding nodes/edges
5. Check exports: Review the generated README.md to verify your agent structure

---

Common Issues

"Node X is unreachable from entry"

• Make sure there's a path of edges from the entry node to all nodes
• Check that you've defined edges connecting your nodes

"Missing required input Y for node X"

• Ensure previous nodes output the required inputs
• Check your input_keys and output_keys match

"Router routes don't match edges"

• Don't worry! The export tool auto-generates missing edges from routes
• If you see this warning, it's informational only

"Cannot find tool Z"

• Verify the tool name matches available tools (e.g., "web_search", "web_fetch")
• Check the required_tools section in the exported agent

---

Resources

• Framework Documentation: See README.md
• Example Agents: Check the exports/ directory for examples
• MCP Protocol: https://modelcontextprotocol.io