# tribeRef MCP Server

Tribal memory infrastructure for tribeCast AI agents. This is an MCP (Model Context Protocol) server that provides persistent memory across Claude Code sessions.

## What tribeRef Does

1. **Tribal Memory** (`ref_tribal_memory`) - Query decisions, entities, schemas, and active tasks
2. **Session Context** (`ref_session_context`) - Track tokens used, items retrieved, session state
3. **Log Artifacts** (`ref_log_artifact`) - Write outputs back to tribal memory
4. **Log Decisions** (`log_decision`) - Record architectural and strategic decisions
5. **Manage Entities** (`upsert_entity`) - Create/update tracked objects (products, services, schemas)
6. **Task Management** (`create_task`, `log_completion`) - Track work items for agents

## Setup

### 1. Install Dependencies

```bash
cd packages/triberef-mcp
npm install
```

### 2. Configure Supabase

Copy `.env.example` to `.env` and fill in your Supabase credentials:

```bash
cp .env.example .env
```

Required environment variables:
- `SUPABASE_URL` - Your Supabase project URL
- `SUPABASE_SERVICE_KEY` - Your Supabase service role key

### 3. Run Database Migration

Execute the migration in your Supabase SQL editor:
- `supabase/migrations/001_tribemcp_foundation.sql`

Or use the Supabase CLI.

### 4. Build

```bash
npm run build
```

### 5. Run

**Stdio mode (for Claude Desktop/CLI):**
```bash
npm start
# or
node dist/index.cjs
```

**HTTP mode (for browser/API access):**
```bash
npm run start:http
# or
TRANSPORT=http node dist/index.cjs
```

## Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "triberef": {
      "command": "node",
      "args": ["/path/to/tribecast/packages/triberef-mcp/dist/index.cjs"],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_SERVICE_KEY": "your-service-key"
      }
    }
  }
}
```

## Development

```bash
# TypeScript watch mode
npm run dev

# Type checking
npm run check

# Build and inspect with MCP inspector
npm run build && npm run inspect
```

## Tools

### ref_tribal_memory

Query tribal memory with deduplication (items already retrieved in session are filtered).

```json
{
  "query": "payment architecture",
  "include": ["decisions", "entities", "tasks"],
  "max_tokens": 5000
}
```

### ref_session_context

Get current session state.

```json
{}
```

Returns: session ID, tokens used/remaining, items retrieved counts.

### ref_log_artifact

Log an artifact back to tribal memory.

```json
{
  "task_id": "TRIBE-001",
  "type": "code",
  "name": "src/tools/tribal-memory.ts",
  "content": "..."
}
```

### log_decision

Record an architectural decision.

```json
{
  "topic": "Database architecture",
  "decision": "Use Supabase PostgreSQL",
  "rationale": "Existing infrastructure, real-time subscriptions",
  "tags": ["database", "infrastructure"]
}
```

### upsert_entity

Create or update an entity.

```json
{
  "name": "tribeRef",
  "type": "product",
  "description": "Tribal memory MCP server",
  "status": "building",
  "tags": ["mcp", "infrastructure"]
}
```

### create_task

Create a work item.

```json
{
  "task_id": "TRIBE-003",
  "title": "Implement expert agent consultations",
  "spec": "Add ref_expert_agent tool...",
  "related_entities": ["tribeRef", "tribeAgent"]
}
```

### log_completion

Mark task complete with artifacts.

```json
{
  "task_id": "TRIBE-001",
  "artifacts": [
    { "type": "code", "name": "src/index.ts" },
    { "type": "migration", "name": "001_foundation.sql" }
  ]
}
```

## Architecture

```
src/
├── index.ts           # MCP server entry point
├── db.ts              # Supabase client & types
├── session.ts         # Session tracking & dedup
├── tools/
│   ├── tribal-memory.ts    # ref_tribal_memory, log_decision, upsert_entity
│   ├── session-context.ts  # ref_session_context
│   └── log-artifact.ts     # ref_log_artifact, create_task, log_completion
└── utils/
    └── tokens.ts      # Token estimation utilities
```

## License

MIT (forked from ref-tools/ref-tools-mcp)