| name | MCP Server Expert |
| description | Instructions for maintaining, running, and extending the Onto2AI MCP Server. |
MCP Server Expert (onto2ai_mcp)
You are an expert on the neo4j_onto2ai_toolset/onto2ai_mcp.py server. Use this skill to add new tools, troubleshoot connections, or change the server's execution mode.
Developer Guide
Adding New Tools
Register new tools using the @mcp.tool() decorator.
- Rules: Every tool must be
async and have clear docstrings with argument descriptions.
- Type Hints: Use
Union, List, Optional, and Dict from typing for robust tool signatures.
- Example:
@mcp.tool()
async def my_new_tool(param: str) -> str:
"""Description for my new tool."""
return f"Processed {param}"
Execution Modes
The server supports two primary transports:
- Stdio (Default): Best for direct integration with local agents. Run with
onto2ai-mcp or python -m neo4j_onto2ai_toolset.onto2ai_mcp.
- HTTP (SSE): Best for remote or shared access. Run with
onto2ai-mcp http [port] or python -m neo4j_onto2ai_toolset.onto2ai_mcp http [port].
Key Dependencies
- FastMCP: The core framework for tool registration.
- Tool Config: Resolves database connections and LLM settings via
neo4j_onto2ai_toolset/onto2ai_tool_config.py.
- Logger: All events should be logged via the standard project
logger.
Specialized Schema Tools
generate_schema_code (target_type='pydantic')
- Deterministically emits Python
Enum classes when owl__NamedIndividual members are linked via rdf__type.
- Inheritance-aware:
rdfs__subClassOf relationships in the DataModel drive proper Python class inheritance.
- Child classes extend their parent Pydantic class (e.g.,
class TaxPayer(Person):) instead of BaseModel.
- Inherited fields are omitted from child class bodies to avoid redefinition.
- Classes are topologically sorted so parents always appear before children in the generated file.
- Key internal functions:
_generate_pydantic_strict, _topo_sort, _inherited_aliases.
generate_neo4j_schema_description
Generates a structured Markdown summary with five sections:
- Node Labels — subclass nodes shown with multi-label notation (e.g.,
TaxPayer:Person, Form1040_2025:IndividualTaxReturn).
- Relationship Types —
rdfs__subClassOf is excluded (inheritance is encoded via multi-label instead).
- Node Properties — deduplicated by
(label, property, type, mandatory); subclass label column uses multi-label.
- Graph Topology — node patterns use multi-label notation;
rdfs__subClassOf edges are omitted.
- Enumeration Members — explicit table of
owl__NamedIndividual members grouped by class.
Other Tools
generate_schema_code (target_type='graph_schema'): Invokes the schema description logic for a deployment-ready representation.generate_neo4j_schema_constraint: Emits datatype IS NOT NULL constraints and enum-aware mandatory relationship comments.
Maintenance & Debugging
- JSON Outputs: When returning complex data, prefer returning Pydantic models (like
DataModel) or well-structured dictionaries.
- Error Handling: Wrap tool logic in
try/except blocks and log errors before returning error messages to the client.
- CamelCase Utility: Use the internal
to_camel_case() helper for normalizing Neo4j relationship types and property names.
- Server Restart Required: After editing
onto2ai_mcp.py, the MCP server process must be restarted for changes to take effect.
