mcp-projects-assistant

mcpassistant/mcp-projects-assistant

3.1

If you are the rightful owner of mcp-projects-assistant and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Projects Assistant is a tool designed to manage the lifecycle and alias management of projects within the MCP ecosystem.

MCP Projects Assistant

Unified project lifecycle and alias management for the MCP ecosystem.

Overview

The Projects Assistant manages all MCP servers and packages in the mcpassistant workspace, providing:

  • Auto-discovery of projects
  • Dynamic alias generation for shell
  • Integration with build assistant
  • Configuration mirroring for multiple systems

Architecture Decisions

Project Hierarchy

mcpassistant/                    # Workspace
ā”œā”€ā”€ mcp-servers/                 # Category
ā”‚   ā””ā”€ā”€ mcp-*-assistant/        # Projects
ā””ā”€ā”€ packages/                    # Category
    ā””ā”€ā”€ @mcpassistant/*         # Packages

What Constitutes a Project

MCP Servers require:

  • package.json with service metadata
  • index.js entry point
  • Port assignment (via gateway registry)
  • Logging integration via @mcpassistant/logging

Packages require:

  • package.json with @mcpassistant/ scope
  • Entry point defined in package.json

Aliases Per Project

Each project gets these aliases:

  • cd-{name} - Navigate to project directory
  • start-{name} - Start tmux session for development
  • join-{name} - Attach to existing tmux session
  • kill-{name} - Kill tmux session
  • edit-{name} - Open in Sublime Text
  • status-{name} - Check service status via gateway
Alias Conflict Resolution

When MCP servers and packages share names (e.g., both "secrets" and "website"), aliases are handled intelligently:

  • MCP servers get priority with clean aliases: cd-secrets ā†’ /mcp-servers/platform/mcp-secrets-assistant
  • Conflicting packages get prefixed aliases: cd-pkg-secrets ā†’ /packages/sdk/integrations/secrets
  • This ensures MCP servers (the primary development tools) are easily accessible while packages remain available

Services auto-launch via the gateway's ecosystem-manager, so no manual start commands needed.

Configuration Mirroring

Master config: mcpassistant/config/projects.json ZSH mirror: ~/.config/zsh/data/projects.json

The master is maintained by this assistant and mirrored to ZSH for alias generation.

No Symlinks

We don't create symlinks in the home directory - aliases handle navigation.

Installation

cd ~/Dropbox\ \(Personal\)/DEV/mcpassistant/mcp-servers/mcp-projects-assistant
npm install

Usage

Start the Service

npm start
# Service runs on port 9107 (platform range: 9100-9119)

Shell Integration

# Refresh project aliases (reloads from Projects Assistant)
projects-refresh

# List all projects
projects

# Navigate to a project
cd-build

# Open project in editor
edit-build

# Start development session
start-build

Create New Project

# Uses mcp-build-assistant to scaffold
new-project calendar

API Endpoints

  • GET /health - Service health check
  • GET /projects - List all projects
  • GET /projects/:name - Get specific project
  • POST /projects - Register new project
  • POST /sync - Sync configuration to mirrors
  • POST /hooks/build-complete - Build assistant webhook
  • GET /services/classifications - Get service lifecycle classifications

Dashboards

  • /dashboard - Projects dashboard with all projects and metadata
  • /service-map - Interactive service dependency visualization

Integration with Build Assistant

When mcp-build-assistant creates a new project:

  1. Scaffolds project in correct location
  2. Sends webhook to /hooks/build-complete
  3. Projects assistant registers the project
  4. Updates configuration mirrors
  5. User runs refresh-projects to get aliases

Logging

Uses @mcpassistant/logging package:

  • Centralized logs in ~/Documents/mcp-assistant/logs/
  • Daily rotation
  • JSON format with correlation IDs

Chezmoi Support

For different usernames across machines:

# In projects.json template
base_path: "{{ .chezmoi.homeDir }}/Dropbox (Personal)/DEV/mcpassistant"

Port Management

Ports are assigned by category:

  • Gateway & Core: 9000-9099
  • Platform services: 9100-9119 (Projects Assistant: 9107)
  • Development tools: 9120-9139
  • Intelligence: 9140-9159

Future Enhancements

  • Support for multiple workspaces
  • Custom project types beyond MCP servers and packages
  • Project templates
  • Dependency tracking between projects
  • Automated testing integration

Configuration

No manual configuration needed - the assistant auto-discovers projects in:

  • mcpassistant/mcp-servers/
  • mcpassistant/packages/

Troubleshooting

Aliases not working

# Check if service is running
curl http://localhost:9107/health

# Force sync
curl -X POST http://localhost:9107/sync

# Reload shell config
source ~/.zshrc
refresh-projects

Project not discovered

  • Ensure project has package.json and index.js
  • Check naming convention (mcp--assistant or @mcpassistant/)
  • Restart projects assistant to force re-scan

License

MIT