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

cd packages/triberef-mcp
npm install

2. Configure Supabase

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

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

npm run build

5. Run

Stdio mode (for Claude Desktop/CLI):

npm start
# or
node dist/index.cjs

HTTP mode (for browser/API access):

npm run start:http
# or
TRANSPORT=http node dist/index.cjs

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.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

# 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).

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

ref_session_context

Get current session state.

{}

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

ref_log_artifact

Log an artifact back to tribal memory.

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

log_decision

Record an architectural decision.

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

upsert_entity

Create or update an entity.

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

create_task

Create a work item.

{
  "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.

{
  "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)