| Name | eventuali-mcp-server JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | MCP server and client for Eventuali event sourcing system with integrated API server |
| upload_time | 2025-08-25 20:34:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
event-sourcing
eventuali
fastmcp
mcp
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="https://raw.githubusercontent.com/primevalai/onyx-octopus/main/assets/onyx-octopus-avatar.png" alt="Onyx Octopus" width="300">
# Eventuali MCP Server
</div>
A Model Context Protocol (MCP) server for the Eventuali event sourcing system, providing real-time event streaming, agent lifecycle management, and workflow orchestration capabilities with integrated API server support.
## Features
- **Real-time Event Streaming**: Continuous polling and streaming of events from Eventuali API
- **Agent Lifecycle Management**: Tools for starting, monitoring, and completing agent workflows
- **Workflow Orchestration**: Support for complex multi-agent workflows with proper correlation
- **Three-Aggregate Pattern**: Enforces proper event naming for Agent, Workflow, and System aggregates
- **Integrated API Server**: Optional auto-start of eventuali-api-server for self-contained operation
- **Type Safety**: Full Pydantic validation and type hints throughout
- **Async Performance**: Built on FastMCP 2.0 for high-performance async operations
## Installation
```bash
pip install eventuali-mcp-server
```
## Quick Start
### Running the MCP Server
```bash
# Start the server on default port 3333
eventuali-mcp-server
# Start with integrated API server (auto-starts eventuali-api-server)
export START_API_SERVER=true
eventuali-mcp-server
# Or specify custom configuration
export EVENT_API_URL=http://localhost:8765
export MCP_PORT=3333
export START_API_SERVER=false
eventuali-mcp-server
```
### Using the Event API Client
```python
from eventuali_mcp_server import EventAPIClient
async def main():
async with EventAPIClient("http://localhost:8765") as client:
# Emit an event
await client.emit_event(
event_name="agent.myAgent.started",
attributes={"agent_id": "my-agent-123"},
aggregate_id="my-agent-123"
)
# Stream events
async for event in client.stream_events():
if event.event == "event_created":
print(f"Received: {event.data}")
```
### MCP Tools
The server provides several MCP tools for event management:
#### Start Agent
```python
await mcp_client.call_tool("start_agent", {
"agent_name": "urlCacher",
"agent_id": "cache-agent-123",
"workflow_id": "workflow-456",
"parent_agent_id": "orchestrator"
})
```
#### Emit Agent Event
```python
await mcp_client.call_tool("emit_agent_event", {
"agent_id": "cache-agent-123",
"agent_name": "urlCacher",
"event_name": "processing_started",
"attributes": {"url_count": 5}
})
```
#### Complete Agent
```python
await mcp_client.call_tool("complete_agent", {
"agent_id": "cache-agent-123",
"agent_name": "urlCacher",
"success": True,
"message": "Successfully cached 5 URLs"
})
```
## Event Naming Convention
The server enforces a three-aggregate event naming pattern:
### Agent Events (`agent.<agentName>.*`)
- Format: `agent.<agentName>.<eventName>`
- Examples: `agent.urlCacher.started`, `agent.simonSays.completed`
- Required: `agent_id`, `agent_name`
- Optional: `workflow_id`, `parent_agent_id`
### Workflow Events (`workflow.*`)
- Format: `workflow.<eventName>`
- Examples: `workflow.started`, `workflow.completed`
- Required: `workflow_id`
- Optional: `user_prompt`
### System Events (`system.*`)
- Format: `system.<eventName>`
- Examples: `system.session_started`, `system.error`
- Optional: `session_id`
## Configuration
Environment variables:
- `EVENT_API_URL`: Eventuali API endpoint (default: `http://127.0.0.1:8765`)
- `MCP_PORT`: MCP server port (default: `3333`)
- `MCP_HOST`: MCP server host (default: `127.0.0.1`)
- `START_API_SERVER`: Auto-start eventuali-api-server (default: `false`)
## Development
### Setup
```bash
git clone https://github.com/primevalai/eventuali-mcp-server
cd eventuali-mcp-server
uv pip install -e ".[dev]"
```
### Running Tests
```bash
uv run pytest
```
### Code Quality
```bash
uv run black .
uv run flake8 .
uv run mypy .
```
## Architecture
The package provides:
- **EventAPIClient**: Async HTTP client for Eventuali API communication
- **MCP Server**: FastMCP-based server with event streaming and tools
- **Models**: Pydantic models for type-safe event handling
- **Tools**: MCP tools for agent and workflow management
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "eventuali-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "event-sourcing, eventuali, fastmcp, mcp",
"author": null,
"author_email": "Primeval AI <noreply@primevalai.com>",
"download_url": "https://files.pythonhosted.org/packages/74/9f/b3a1896b327ccdca1617264e221f3b95f3c0e20fe705e383ea6593bf0461/eventuali_mcp_server-0.2.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/primevalai/onyx-octopus/main/assets/onyx-octopus-avatar.png\" alt=\"Onyx Octopus\" width=\"300\">\n \n # Eventuali MCP Server\n</div>\n\nA Model Context Protocol (MCP) server for the Eventuali event sourcing system, providing real-time event streaming, agent lifecycle management, and workflow orchestration capabilities with integrated API server support.\n\n## Features\n\n- **Real-time Event Streaming**: Continuous polling and streaming of events from Eventuali API\n- **Agent Lifecycle Management**: Tools for starting, monitoring, and completing agent workflows\n- **Workflow Orchestration**: Support for complex multi-agent workflows with proper correlation\n- **Three-Aggregate Pattern**: Enforces proper event naming for Agent, Workflow, and System aggregates\n- **Integrated API Server**: Optional auto-start of eventuali-api-server for self-contained operation\n- **Type Safety**: Full Pydantic validation and type hints throughout\n- **Async Performance**: Built on FastMCP 2.0 for high-performance async operations\n\n## Installation\n\n```bash\npip install eventuali-mcp-server\n```\n\n## Quick Start\n\n### Running the MCP Server\n\n```bash\n# Start the server on default port 3333\neventuali-mcp-server\n\n# Start with integrated API server (auto-starts eventuali-api-server)\nexport START_API_SERVER=true\neventuali-mcp-server\n\n# Or specify custom configuration\nexport EVENT_API_URL=http://localhost:8765\nexport MCP_PORT=3333\nexport START_API_SERVER=false\neventuali-mcp-server\n```\n\n### Using the Event API Client\n\n```python\nfrom eventuali_mcp_server import EventAPIClient\n\nasync def main():\n async with EventAPIClient(\"http://localhost:8765\") as client:\n # Emit an event\n await client.emit_event(\n event_name=\"agent.myAgent.started\",\n attributes={\"agent_id\": \"my-agent-123\"},\n aggregate_id=\"my-agent-123\"\n )\n \n # Stream events\n async for event in client.stream_events():\n if event.event == \"event_created\":\n print(f\"Received: {event.data}\")\n```\n\n### MCP Tools\n\nThe server provides several MCP tools for event management:\n\n#### Start Agent\n```python\nawait mcp_client.call_tool(\"start_agent\", {\n \"agent_name\": \"urlCacher\",\n \"agent_id\": \"cache-agent-123\",\n \"workflow_id\": \"workflow-456\",\n \"parent_agent_id\": \"orchestrator\"\n})\n```\n\n#### Emit Agent Event\n```python\nawait mcp_client.call_tool(\"emit_agent_event\", {\n \"agent_id\": \"cache-agent-123\",\n \"agent_name\": \"urlCacher\",\n \"event_name\": \"processing_started\",\n \"attributes\": {\"url_count\": 5}\n})\n```\n\n#### Complete Agent\n```python\nawait mcp_client.call_tool(\"complete_agent\", {\n \"agent_id\": \"cache-agent-123\",\n \"agent_name\": \"urlCacher\", \n \"success\": True,\n \"message\": \"Successfully cached 5 URLs\"\n})\n```\n\n## Event Naming Convention\n\nThe server enforces a three-aggregate event naming pattern:\n\n### Agent Events (`agent.<agentName>.*`)\n- Format: `agent.<agentName>.<eventName>`\n- Examples: `agent.urlCacher.started`, `agent.simonSays.completed`\n- Required: `agent_id`, `agent_name`\n- Optional: `workflow_id`, `parent_agent_id`\n\n### Workflow Events (`workflow.*`)\n- Format: `workflow.<eventName>`\n- Examples: `workflow.started`, `workflow.completed`\n- Required: `workflow_id`\n- Optional: `user_prompt`\n\n### System Events (`system.*`)\n- Format: `system.<eventName>`\n- Examples: `system.session_started`, `system.error`\n- Optional: `session_id`\n\n## Configuration\n\nEnvironment variables:\n\n- `EVENT_API_URL`: Eventuali API endpoint (default: `http://127.0.0.1:8765`)\n- `MCP_PORT`: MCP server port (default: `3333`)\n- `MCP_HOST`: MCP server host (default: `127.0.0.1`)\n- `START_API_SERVER`: Auto-start eventuali-api-server (default: `false`)\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/primevalai/eventuali-mcp-server\ncd eventuali-mcp-server\nuv pip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Code Quality\n\n```bash\nuv run black .\nuv run flake8 .\nuv run mypy .\n```\n\n## Architecture\n\nThe package provides:\n\n- **EventAPIClient**: Async HTTP client for Eventuali API communication\n- **MCP Server**: FastMCP-based server with event streaming and tools\n- **Models**: Pydantic models for type-safe event handling\n- **Tools**: MCP tools for agent and workflow management\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server and client for Eventuali event sourcing system with integrated API server",
"version": "0.2.2",
"project_urls": {
"Bug Reports": "https://github.com/primevalai/eventuali-mcp-server/issues",
"Documentation": "https://github.com/primevalai/eventuali-mcp-server#readme",
"Homepage": "https://github.com/primevalai/eventuali-mcp-server",
"Repository": "https://github.com/primevalai/eventuali-mcp-server"
},
"split_keywords": [
"event-sourcing",
" eventuali",
" fastmcp",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "749fb3a1896b327ccdca1617264e221f3b95f3c0e20fe705e383ea6593bf0461",
"md5": "c1cf74efdaa636c85bafbffd91221146",
"sha256": "d7d013c53bc5e1f9e8546bd536a95aacdbc8d922492ace4d778734eabba5f8c3"
},
"downloads": -1,
"filename": "eventuali_mcp_server-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "c1cf74efdaa636c85bafbffd91221146",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12772,
"upload_time": "2025-08-25T20:34:48",
"upload_time_iso_8601": "2025-08-25T20:34:48.765930Z",
"url": "https://files.pythonhosted.org/packages/74/9f/b3a1896b327ccdca1617264e221f3b95f3c0e20fe705e383ea6593bf0461/eventuali_mcp_server-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 20:34:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "primevalai",
"github_project": "eventuali-mcp-server",
"github_not_found": true,
"lcname": "eventuali-mcp-server"
}
