convez.ai
MCP Server
Maless88

Roadboard

Maless88/Roadboard

Ver no GitHub
BomPluginScore · de 0 a 100

Multi-project execution, memory, and collaboration platform for humans and AI agents — REST + 31 MCP tools, Postgres + Memgraph, self-hosted deploy.

Instalação

$npx convez-ai Maless88/Roadboard

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
2
Saúde
100%
Último commit
há 2 semanas
Versão
—
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

RoadBoard 2.0

Multi-project execution, memory, and collaboration platform for humans and AI agents.

CI Status

Work in progress. RoadBoard 2.0 is under active development and not yet in beta. APIs, data models, and interfaces may change without notice. Not recommended for production use.


Why RoadBoard exists

Context loss is one of the most expensive problems in modern project work.

Teams lose track of decisions. Agents restart sessions without knowing what happened. Progress is scattered across chat threads, documents, and memory that belongs to no system. Work is repeated because no one can find what was already done.

RoadBoard is designed to be the operational control plane for complex project work — a single place where humans and AI agents share structured project state, preserve memory across sessions, and coordinate without losing context.


Core capabilities

  • Multi-project planning — projects, phases, milestones, tasks, priorities, and dependencies
  • Operational memory — persistent memory entries, decision records, and session handoffs
  • Team collaboration — users, teams, project grants, role-based access control
  • MCP agent access — 34 tools for agents to read and write project state via Model Context Protocol, with fine-grained per-token scope enforcement
  • Atlas (CodeFlow) — interactive architecture map with domain groups, agent context view, drift validation, and Deep Code Map schema (File/Symbol/ExternalPackage)
  • Audit trail — full activity log per project with filters by event type, actor type, and date range
  • Project thumbnails — auto-refresh screenshots from project home URL + manual upload
  • AI assistant — per-project chatbot config supporting Anthropic, OpenAI, and Ollama
  • Web dashboard — swipeable project cards, skeleton loaders, task management, Atlas
  • Async job layer — background refresh, summary generation, thumbnail refresh, and cleanup via BullMQ
  • Local sync bridge — offline-first SQLite journal with sync engine to the central database

Architecture

apps/
  core-api          NestJS — projects, phases, tasks, memory, decisions, codeflow, release (port 3001)
  auth-access       NestJS — users, teams, sessions, MCP tokens (port 3002)
  mcp-service       MCP server (stdio + HTTP) — 34 tools for agent integration (port 3005)
  web-app           Next.js 15 — dashboard, project detail, task management, Atlas (port 3000)
  worker-jobs       NestJS + BullMQ — async jobs: refresh, summary, cleanup (port 3003)
  local-sync-bridge NestJS + SQLite — offline-first journal with sync engine (port 3004)

packages/
  domain            shared enums and domain types
  database          Prisma schema, migrations, seed
  auth              password hashing, token utilities
  grants            permission logic
  mcp-contracts     MCP tool schemas
  api-contracts     shared REST API types
  graph-db          Memgraph (Neo4j-compat) client + Cypher schema for CodeFlow
  demo-seed         seed content for "Tour Roadboard" demo project on signup
  local-storage     SQLite local-storage abstraction
  observability     logging/tracing setup
  config            env helpers

infra/
  docker/           docker-compose (PostgreSQL 16, Redis 7, Memgraph 2.18)
  systemd/          systemd .service + .path units for self-hosted deploy

Stack

  • Runtime: Node.js 20, TypeScript strict
  • Backend: NestJS 11 with Fastify adapter
  • Frontend: Next.js 15 App Router, Tailwind CSS 4
  • Database: PostgreSQL 16 (Prisma ORM), SQLite (local journal)
  • Queue: Redis 7 + BullMQ
  • Agent protocol: MCP (Model Context Protocol) via HTTP StreamableHTTP or stdio
  • Monorepo: pnpm workspaces + Turborepo

Quickstart

Prerequisites

  • Node.js 20+
  • pnpm 9+
  • Docker (for PostgreSQL and Redis)

Setup

# Clone
git clone https://github.com/Maless88/Roadboard.git
cd rb

# Install dependencies
pnpm install

# Copy env and start infrastructure
cp .env.example .env
docker compose -f infra/docker/docker-compose.yml up -d

# Build all packages
pnpm build

The local Docker Compose stack now bootstraps Postgres, Redis, migrations, seed data, core-api, auth-access, mcp-service (HTTP on :3005), worker-jobs, local-sync-bridge, and the Next.js web-app.

Full local stack

# Build and run the full local stack
docker compose -f infra/docker/docker-compose.yml up -d --build

# Stop it
docker compose -f infra/docker/docker-compose.yml down

Start services

# core-api
DATABASE_URL="postgresql://roadboard:roadboard@localhost:5433/roadboard" \
  CORE_API_PORT=3001 AUTH_ACCESS_PORT=3002 \
  node apps/core-api/dist/main.js

# auth-access
DATABASE_URL="postgresql://roadboard:roadboard@localhost:5433/roadboard" \
  AUTH_ACCESS_PORT=3002 \
  node apps/auth-access/dist/main.js

# web-app (dev)
cd apps/web-app && pnpm dev

# worker-jobs
WORKER_JOBS_PORT=3003 node apps/worker-jobs/dist/main.js

# local-sync-bridge
LOCAL_SYNC_PORT=3004 JOURNAL_DB_PATH=.agent/journal.db \
  node apps/local-sync-bridge/dist/main.js

# mcp-service (HTTP mode)
MCP_TRANSPORT=http MCP_HTTP_PORT=3005 AUTH_ACCESS_PORT=3002 \
  node apps/mcp-service/dist/main.js

MCP server (for Claude / agent integration)

{
  "mcpServers": {
    "roadboard": {
      "command": "node",
      "args": ["apps/mcp-service/dist/main.js"],
      "env": {
        "MCP_TOKEN": "<your-mcp-token>",
        "CORE_API_PORT": "3001",
        "AUTH_ACCESS_PORT": "3002"
      }
    }
  }
}

For HTTP MCP clients, use http://127.0.0.1:3005/mcp with a bearer token issued by auth-access. Tokens carry a scopes array (GrantType[]) — each tool enforces the minimum required scope at call time.

API docs

  • core-api: http://127.0.0.1:3001/docs
  • auth-access: http://127.0.0.1:3002/docs

Health endpoints

  • core-api: http://127.0.0.1:3001/health
  • auth-access: http://127.0.0.1:3002/health
  • worker-jobs: http://127.0.0.1:3003/health
  • local-sync-bridge: http://127.0.0.1:3004/health
  • mcp-service: http://127.0.0.1:3005/health
  • web-app: http://127.0.0.1:3000/health

Seeded onboarding data

db:seed now creates a usable local onboarding state for roadboard-2:

  • demo users and team memberships
  • the Roadboard 2.0 project and admin grant
  • the Wave 2 — Platform Hardening phase
  • Wave 2 task and memory history aligned with the current repo state

MCP Tools

Each tool enforces a minimum GrantType scope. project.admin bypasses all checks.

ToolRequired scopeDescription
initial_instructions—Operational protocol bootstrap (call once per session)
list_projectsproject.readList accessible projects
list_teamsproject.readList teams the caller belongs to (slug + role)
get_projectproject.readGet project details with phases
list_active_tasksproject.readList tasks, optionally filtered by status
list_phasesproject.readList phases for a project
get_project_memoryproject.readList memory entries
prepare_task_contextproject.readFull context bundle for a specific task
prepare_project_summaryproject.readProject snapshot for agent onboarding
get_project_changelogproject.readStructured changelog: tasks, phases, decisions, memory, audit
search_memoryproject.readFull-text search over memory entries
list_recent_decisionsproject.readList decisions, optionally filtered by status
create_tasktask.writeCreate a task in a phase (auto-selects first phase if omitted); accepts description, assigneeId, dueDate
update_tasktask.writeUpdate title, description, phaseId, priority, assigneeId, or dueDate of an existing task
update_task_statustask.writeUpdate task status; accepts completionReport when marking done
create_phaseproject.writeCreate a roadmap phase; can be linked to a decision via decisionId
update_phaseproject.writeUpdate phase fields: title, status, dates, linked decision
create_memory_entrymemory.writeCreate a memory entry
create_handoffmemory.writeStructured handoff entry for session continuity
create_decisiondecision.writeRecord an architectural decision; auto-logs to vault
update_decisiondecision.writeRecord outcome, change status, set resolvedAt
create_projectproject.adminCreate a new project; auto-logs to vault
get_architecture_mapcodeflow.readGet the architecture graph (nodes + edges)
get_node_contextcodeflow.readFull context for an architecture node
create_architecture_repositorycodeflow.writeRegister a CodeRepository for the project (one per onboarding)
create_architecture_nodecodeflow.writeAdd a workspace/module/service ArchitectureNode
create_architecture_edgecodeflow.writeAdd a depends_on / imports edge between two nodes
create_architecture_linkcodeflow.writeTie a Task / Decision / Memory entry to an ArchitectureNode
link_task_to_nodecodeflow.writeSemantic wrapper of create_architecture_link for tasks (call right after create_task)
create_architecture_annotationcodeflow.writeAttach a free-text note to an ArchitectureNode
ingest_architecturecodeflow.writeOne-shot orchestrator: repository + nodes + edges + annotations in a single manifest call

Development

pnpm typecheck       # typecheck all packages
pnpm -r test         # run all tests
pnpm -r build        # build all packages and apps

Documentation


Current status

Waves 1–5 are complete. The platform is functional end-to-end: REST APIs, MCP server, web dashboard, async jobs, local sync bridge, dual-write graph DB (Postgres + Memgraph), and self-hosted deploy are all implemented.

  • Wave 3 — semantic memory search, agent-readable project changelog, richer decision model, memory summarization background jobs ✓
  • Wave 4 — fine-grained MCP token scopes, project ownership model, per-project member management, MCP auto-vault, Phase–Decision linking, interactive Roadmap and Decisions accordions, 4 new MCP write tools ✓
  • Wave 5.1 — Atlas (CodeFlow) manual MVP: ArchitectureNode/Edge/Link/Annotation, MCP atomic write tools, Architecture Map canvas in web-app, node detail drawer ✓
  • Wave 5.2 — graph DB foundation: Memgraph 2.18 added to compose, @roadboard/graph-db Neo4j-compat client, dual-write GraphSyncService for nodes/edges, schema constraints + indexes ✓
  • Wave 5.3 — agent-driven onboarding: ingest_architecture one-shot orchestrator, link_task_to_node semantic wrapper, enriched prepare_task_context with architecture nodes & decisions ✓
  • Deploy UX — light/dark theme, single-pill release banner, self-hosted per-host deploy via systemd.path + systemd.service (no GitHub Actions workflow_dispatch needed) ✓

Active planning: Wave 6 — Deep Code Map (file + symbol graph via ts-morph + tree-sitter, blast-radius queries on Memgraph) and CF-GDB-03b (cut over Atlas reads from Postgres to Memgraph and retire the architecture_* Prisma tables).

The project is pre-beta. No stable release has been published yet. Breaking changes may occur on main.


Contributing

See CONTRIBUTING.md.


License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados