@zerospacegg/anrubic/release-artifacts/README.md

Anrubic - ZeroSpace.gg MCP Server for AI agents to access game data

# 🔮 Anrubic - ZeroSpace.gg MCP Server

**Anrubic** is a Model Context Protocol (MCP) server that provides AI agents with real-time access to ZeroSpace game data. Named after the cosmic entity that leads the Xol Collective, Anrubic serves as your bridge between the interdimensional game data empire and AI assistants.

## 🚀 Quick Start

### Prerequisites

- Node.js 18+
- Built iolin package (`just build-iolin` from project root)

### Build & Test

```bash
# From project root
just build-anrubic

# Test the server
cd anrubic
node test-mcp.js
```

### Manual Testing

```bash
# Start the server
node dist/index.js

# In another terminal, send a test request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.js
```

## 🛠️ MCP Client Setup

### Claude Desktop

1. Locate your Claude Desktop config file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add Anrubic to your configuration:

```json
{
  "mcpServers": {
    "anrubic": {
      "command": "node",
      "args": ["/absolute/path/to/zsgg/anrubic/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

3. Restart Claude Desktop

### Cursor IDE

Add to your Cursor settings or workspace configuration:

```json
{
  "mcp.servers": {
    "anrubic": {
      "command": "node",
      "args": ["/absolute/path/to/zsgg/anrubic/dist/index.js"]
    }
  }
}
```

### Other MCP Clients

Anrubic uses the standard MCP stdio transport. Configure your client to run:

```bash
node /path/to/zsgg/anrubic/dist/index.js
```

## 🔧 Available Tools

### `get_tags`
Get all available ZeroSpace tags with metadata.

**Parameters**: None

**Example**:
```json
{
  "name": "get_tags",
  "arguments": {}
}
```

### `get_faction_data`
Get all units, buildings, and abilities for a specific faction.

**Parameters**:
- `faction` (string): Faction name (e.g., "Terran Alliance", "Xol Collective")

**Example**:
```json
{
  "name": "get_faction_data",
  "arguments": {
    "faction": "Terran Alliance"
  }
}
```

### `fetch_entity_by_id`
Get detailed information about a specific entity by its ID.

**Parameters**:
- `id` (string): Entity ID

**Example**:
```json
{
  "name": "fetch_entity_by_id",
  "arguments": {
    "id": "marine"
  }
}
```

### `all_ids`
Get all entity IDs with optional filtering by type or faction.

**Parameters**:
- `type` (optional string): Filter by entity type (unit, building, ability)
- `faction` (optional string): Filter by faction

**Example**:
```json
{
  "name": "all_ids",
  "arguments": {
    "type": "unit",
    "faction": "Terran Alliance"
  }
}
```

### `search_entities`
Search entities by name, description, or tags.

**Parameters**:
- `query` (string): Search query
- `limit` (optional number): Maximum results (default: 10)

**Example**:
```json
{
  "name": "search_entities",
  "arguments": {
    "query": "marine",
    "limit": 5
  }
}
```

## 📊 Available Resources

### `anrubic://status`
Server status and data loading statistics.

### `anrubic://factions`
List of all available factions with entity counts.

## 🏗️ Development

### Project Structure

```
anrubic/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript output
├── test-mcp.js          # Test script
├── claude-config.json   # Example Claude Desktop config
├── package.json
├── tsconfig.json
└── README.md
```

### Building

```bash
# Development build with watch mode
npm run watch

# Production build
npm run build

# Clean build artifacts
npm run clean
```

### Data Source

Anrubic loads game data from the iolin package's JSON output:
- `../iolin/dist/json/all.json` - All game entities
- `../iolin/dist/json/tags.json` - Tag definitions

Make sure iolin is built first: `just build-iolin`

## 🚨 Troubleshooting

### "Failed to load game data"

**Cause**: iolin JSON files not found or corrupted.

**Solution**:
```bash
# From project root
just build-iolin
just build-anrubic
```

### "Command not found" in MCP client

**Cause**: Incorrect path to the Anrubic executable.

**Solution**: Use absolute paths in your MCP client configuration.

### TypeScript compilation errors

**Cause**: Strict TypeScript settings or missing type definitions.

**Solution**:
```bash
npm run clean
npm run build
```

### Server hangs or doesn't respond

**Cause**: Malformed JSON or MCP protocol issues.

**Solution**:
1. Test with the provided test script: `node test-mcp.js`
2. Check server logs (stderr output)
3. Validate JSON-RPC requests

## 📈 Performance Notes

- **Cold start**: ~1-2 seconds to load game data
- **Memory usage**: ~50-100MB depending on game data size
- **Response time**: <100ms for most queries
- **Data freshness**: Reloads when server restarts

## 🤝 Integration Examples

### With Claude Desktop

Ask Claude:
> "Show me all Terran Alliance units with their stats"

Claude will use the `get_faction_data` tool automatically.

### With Cursor

Configure Anrubic as an MCP server, then ask:
> "Help me analyze the unit balance between factions"

### Programmatic Usage

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["/path/to/anrubic/dist/index.js"]
});

const client = new Client({
  name: "my-client",
  version: "1.0.0"
});

await client.connect(transport);

// Get all tags
const tags = await client.callTool({
  name: "get_tags",
  arguments: {}
});

console.log(tags);
```

## 🌟 Future Enhancements

- [ ] Real-time data updates via file watching
- [ ] Caching layer for improved performance
- [ ] GraphQL-style query capabilities
- [ ] Unit matchup calculations
- [ ] Build order optimization suggestions
- [ ] Competitive meta analysis

## 📄 License

ISC License - Part of the ZeroSpace.gg community project.

## 🔗 Related

- [iolin](../iolin/) - Game data extraction engine
- [vynthra](../vynthra/) - Discord bot with similar functionality
- [ZeroSpace.gg](https://zerospace.gg) - Community website

---

*"Through the cosmic void, data flows eternal. Anrubic bridges dimensions, bringing order to chaos."* - Princess Ruby of R'lyeh