convez.ai
MCP ServerDevOps & InfraestruturaAvançado
reybenbaq

Projects Cockpit MCP

reybenbaq/projects-cockpit-mcp

Visão em tempo real de workspace multi-projeto para Claude via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP read-only que fornece ao Claude visão estruturada em tempo real de um workspace multi-projeto: lista de projetos, subagentes, planos em andamento, estado Git e busca em arquivos de memória. Construído com SDK oficial Python, HTTP streamable e Docker, com autenticação por bearer token.

Instalação

$npx convez-ai reybenbaq/projects-cockpit-mcp

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
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
7
Contribuidores
2

Casos de uso

  • Manter Claude informado sobre estado de múltiplos projetos simultaneamente
  • Consultar planos e status de agentes em um workspace distribuído
  • Realizar buscas rápidas em documentação e memória de projetos
  • Integrar awareness de Git e organização de projetos em workflows com Claude

Veredito

Servidor MCP bem arquitetado e hardened, com implementação production-ready (SDK oficial, HTTP streamable, Docker, auth bearer). Portfolio técnico sólido que demonstra design defensivo; útil principalmente para equipes que gerenciam workspaces multi-projeto complexos e querem dar ao Claude acesso estruturado a essa realidade.

README

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

Projects Cockpit MCP

CI License: MIT Python 3.12 MCP protocol 2025-11-25

A read-only Model Context Protocol server. It gives an AI host (Claude Code, Claude Desktop) live, structured awareness of a multi-project workspace: what projects exist, which subagents are defined, what plans are in flight, the git state of each repo, and a fast grep over memory files.

Built on the official Python MCP SDK with FastMCP, served over streamable-HTTP, and packaged to run in Docker. It ships zero data. Point PROJECTS_ROOT at any directory tree and it scans that.

  • Protocol revision: 2025-11-25
  • SDK: mcp[cli] >=1.25,<2.0 (official Python MCP SDK)
  • Transport: streamable-HTTP, bound to loopback, bearer-token auth

This is a portfolio sample. It exists to show that I can design, harden, and ship a real MCP server end to end: official SDK, streamable-HTTP transport, hardened container, bearer auth, supply-chain CI, and a live-client integration test. It is also a tool I actually use, published as a runnable reference so you can clone it, bring it up, and connect Claude yourself. It is not a hosted service and not a maintained dependency.

Tools

ToolArgumentsReturns
list_projects(none)Each discovered project with name / path / has_agent / has_git / plan_count / is_dirty flags
list_agentsproject?Subagent definitions (name, description, model) parsed from .claude/agents/*.md frontmatter
list_plansstatus?, project?Plan documents and their **Status:** (DRAFT / APPROVED / IN PROGRESS / IMPLEMENTED / BLOCKED)
project_statusproject, recent=5Git branch, dirty state, ahead/behind vs upstream, recent commits
memory_searchquery, scope?Case-insensitive line matches across MEMORY.md, feedback_*, reference_*, project_*, user_*. scope narrows to files with that name prefix

All tools carry readOnlyHint=True and openWorldHint=False in their MCP annotations, so hosts that inspect tool metadata can auto-permit reads. There is no write path.

Relative-path tool inputs

The project argument on project_status, list_agents, and list_plans takes the project's relative path from PROJECTS_ROOT:

  • Nested projects use their full relative path: "Automation/SalesBot", "Client/Acme Corp".
  • Top-level (L1) projects use their bare directory name: "Wordpress", "Standards Agent".
  • Bare leaf names are not resolved for nested projects. Passing "SalesBot" when the project lives at Automation/SalesBot will not find it. Always pass the full relative path for nested projects.
project_status(project="Automation/SalesBot")    # nested — full relative path required
project_status(project="Wordpress")              # L1 — bare name is the full relative path
list_agents(project="Automation/SalesBot")
list_plans(project="Client/Acme Corp")

The path must be relative (no leading /) and must not escape PROJECTS_ROOT via ... Absolute paths and traversal attempts are rejected.

Supported workspace layouts

The cockpit supports both flat and nested directory layouts, and handles mixed/irregular trees.

Flat layout (all projects at the top level):

PROJECTS_ROOT/
  My Bot/
  My Website/
  Shared Lib/

Nested layout (real multi-category workspaces with sub-categories):

PROJECTS_ROOT/
  Automation/
    SalesBot/             <-- discovered as "Automation/SalesBot"
    ReportBot/            <-- discovered as "Automation/ReportBot"
  Client/
    Acme Corp/            <-- discovered as "Client/Acme Corp"
  Standards Agent/        <-- discovered as "Standards Agent"
  portfolio-samples/
    projects-cockpit-mcp/ <-- discovered at depth 2

Discovery is marker-based and recursive up to MAX_DISCOVERY_DEPTH (default 3). A directory qualifies as a project when it carries at least one marker:

  • .claude/agents/ with at least one *.md file
  • A valid .git repository (.git/HEAD is a regular file)
  • A plans and validations/ or implemented plans/ or Plans/ subdirectory

Both a parent directory and a nested child qualify simultaneously with no suppression. If Automation/ itself carries an agent definition, it surfaces alongside Automation/SalesBot.

Architecture

src/cockpit/
  server.py       FastMCP instance, tool registration, ASGI app, main()
  config.py       env → frozen Config (load-once, fail-fast)
  scanner.py      project / agent / plan filesystem scans (marker-based, recursive)
  gitinfo.py      git via subprocess argument lists (no shell)
  search.py       pure-Python memory grep (no ripgrep dependency)
  security.py     path-containment guard (traversal defense)
  middleware.py   ASGI bearer-token enforcement
  models.py       dataclass output schemas

Tools are registered inside build_server(config) so they close over an injected config. Nothing reads the environment on import, which keeps the package testable without a populated environment.

Design notes

  • Discovery uses a single _iter_project_dirs function shared by list_projects, list_agents, and list_plans. No duplication of traversal logic.
  • Tools that read the filesystem or run git are async and offload the blocking work with anyio.to_thread.run_sync. FastMCP runs sync tools directly on the event loop, so blocking there would stall every concurrent request.
  • Each tool returns a dataclass. FastMCP derives the outputSchema from it and emits both structuredContent and a text mirror.
  • The bearer middleware is raw ASGI, not Starlette's BaseHTTPMiddleware. That base class breaks streamed responses and swallows lifespan events, which the streamable-HTTP transport depends on.
  • project_status validates that the target directory is a real git repo (.git/HEAD is a file) before invoking any git subprocess. An empty or corrupted .git directory returns a ToolError rather than an unhandled subprocess failure.
  • memory_search uses os.walk with in-place directory pruning to skip excluded subtrees (.venv/, node_modules/, etc.) rather than an unbounded rglob. On NTFS-over-WSL2, this avoids traversing thousands of irrelevant files.

Configuration

All configuration is loaded from environment variables at startup. Required variables are validated together and all problems are reported in a single error.

VariableDefaultDescription
PROJECTS_ROOTrequiredDirectory scanned for projects, agents, and plans
COCKPIT_TOKENrequiredBearer token required on every HTTP request
MEMORY_ROOTPROJECTS_ROOTDirectory searched by memory_search. Set this explicitly when your memory files live in a different tree from your project code. When unset, the cockpit searches PROJECTS_ROOT (correct for workspace roots that contain both), but a memory_search pointed at a large code tree will be slower.
MAX_DISCOVERY_DEPTH3How many directory levels below PROJECTS_ROOT to recurse. Covers L1/L2/L3 layouts; raising above 3 risks descending into vendored subdirectories.
REQUIRE_MARKERStrueWhen true, only directories with at least one project marker (agent def, git repo, plans dir) are returned. Set to false to surface all non-excluded directories regardless of markers. Useful for flat demo or CI environments with minimal fixture trees.
PORT8848Bind port (must be ≥ 1024 for non-root container operation)
HOST127.0.0.1Bind address
ALLOWED_ORIGINSloopback originsComma-separated browser Origin values the transport accepts
ALLOWED_HOSTSloopback hostsComma-separated Host header values the transport accepts
MAX_SEARCH_HITS50Hard ceiling on memory_search results
LOG_LEVELINFORoot log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Run in Docker

This repo holds the source. You run the container yourself. Nothing is hosted. Clone it, point it at your own workspace, and bring it up:

cp .env.example .env
# edit .env: set PROJECTS_ROOT_HOST to your workspace and COCKPIT_TOKEN to a random value
docker compose up --build

The server listens on http://127.0.0.1:8848/mcp. Compose mounts the workspace read-only. The container runs as a non-root user with cap_drop: ALL, a read_only root filesystem, and no-new-privileges.

Health probe (no token required): GET http://127.0.0.1:8848/healthz.

Connect from Claude Code

Add to your project .mcp.json (or ~/.claude.json for user scope):

{
  "mcpServers": {
    "projects-cockpit": {
      "type": "http",
      "url": "http://127.0.0.1:8848/mcp",
      "headers": { "Authorization": "Bearer <COCKPIT_TOKEN>" }
    }
  }
}

Then ask: "Which plans are IN PROGRESS?", "List my agents.", "Which repos are dirty?", "Search memory for rate limits.", "What agents are in the GCP category?"

Local development

pip install -e ".[dev]"
pytest                       # unit + smoke tests
pytest --cov=cockpit         # with coverage

Tests and supply-chain CI

The suite is 103 tests (87.44% branch coverage): the scanner (flat and nested discovery, marker gate, depth limit, exclusions, capital-P plans dir, parent+child surfacing, path-qualified names), search (excluded-dir pruning, whitespace-only query guard), git parsing, config boundaries (including MAX_DISCOVERY_DEPTH and REQUIRE_MARKERS), the transport-security 421 and 403 paths, the bearer middleware, path-traversal plus symlink containment (including multi-segment inputs), invalid-git graceful handling, tool annotations (readOnlyHint=True, openWorldHint=False, title present on every tool), and Pydantic schema-boundary validation (parameter descriptions in inputSchema, range constraints enforced before handler invocation). CI enforces an 85% branch-coverage gate. One test pins the protocol revision by asserting the SDK's LATEST_PROTOCOL_VERSION equals the value the README advertises.

Every GitHub Actions step is pinned to a full commit SHA with a trailing version comment. The image-scan job builds the container and fails on any HIGH or CRITICAL vulnerability (Trivy). Dependabot keeps the SHA pins and the dependencies current.

The server is also validated end to end against a live MCP client. A real ClientSession over streamable-HTTP completes the initialize handshake (protocol 2025-11-25) and calls all five tools. Every call returns correct structured data, with the container running non-root on a read-only root filesystem.

Security model

This server runs locally (a container published on host loopback only), so it uses a static bearer token plus Origin validation. That is the MCP spec's baseline for local HTTP servers: validate Origin, bind loopback, require a token.

A remote deployment exposing anything beyond public data needs full OAuth 2.1 (PKCE, audience-bound tokens, Protected Resource Metadata). The official SDK supports this via TokenVerifier + AuthSettings. Swapping the static-token middleware for that path is the intended upgrade, out of scope for this local sample.

Notes:

  • The FastMCP transport layer owns Host and Origin validation (the DNS-rebinding defense), configured explicitly in build_server. By default it accepts only loopback Host and Origin headers. A request with no Origin (a non-browser client like Claude Code) is allowed. A disallowed Origin returns 403 and a disallowed Host returns 421. Widen ALLOWED_HOSTS and ALLOWED_ORIGINS only to expose the server beyond loopback, and adopt the OAuth path below when you do.
  • The ASGI middleware adds the one control the transport layer lacks: a bearer token, required on every request and compared in constant time (hmac.compare_digest).
  • The server resolves every caller-supplied project or file name and checks containment before any read (security.resolve_within). Discovery skips symlinks so a planted link cannot redirect a scan outside the workspace. Multi-segment relative paths (e.g. "Automation/SalesBot") are supported; absolute paths and .. traversals are rejected.
  • Git invocations use argument lists, never a shell string.

License

MIT.

Ver o original no GitHub

Bom para

Relacionados