Crate foundry_mcp

Crate foundry_mcp 

Source
Expand description

Project Manager MCP Server Library

A Model Context Protocol (MCP) server for managing software projects with specifications, tasks, and notes. This library provides AI coding assistants with structured project context and deterministic state management for complex software development workflows.

§Overview

The Project Manager MCP server enables AI coding assistants to:

  • Create and manage projects with technology stacks and business vision
  • Write detailed specifications for features and requirements
  • Track implementation tasks with dependencies and priorities
  • Capture development notes and decisions throughout the process
  • Load contextual information to maintain continuity across coding sessions

§Architecture

The library is organized into several key modules:

  • models - Core data structures (Project, Specification, Task, Note)
  • repository - Data access layer for persistent storage
  • filesystem - Safe file system operations and management
  • handlers - MCP tool implementations for the protocol interface
  • errors - Comprehensive error types and handling
  • utils - Utility functions for validation and formatting

§Usage

§As an MCP Server

The primary use case is running as an MCP server that AI coding assistants can connect to:

# Run the MCP server
cargo run --bin foundry-mcp

§As a Library

You can also use the library directly in Rust applications:

use project_manager_mcp::{
    ProjectRepository, SpecificationRepository, FileSystemManager,
    Project, TechStack, Vision, ProjectManagerError
};
use chrono::Utc;

// Set up the file system manager
let fs_manager = FileSystemManager::new()?;

// Create repositories
let project_repo = ProjectRepository::new(fs_manager.clone());
let spec_repo = SpecificationRepository::new(fs_manager);

// Create a new project
let project = Project {
    name: "my-web-app".to_string(),
    description: "A modern web application".to_string(),
    created_at: Utc::now(),
    updated_at: Utc::now(),
    tech_stack: TechStack {
        languages: vec!["Rust".to_string(), "TypeScript".to_string()],
        frameworks: vec!["Actix-Web".to_string(), "React".to_string()],
        databases: vec!["PostgreSQL".to_string()],
        tools: vec!["Cargo".to_string(), "npm".to_string()],
        deployment: vec!["Docker".to_string()],
    },
    vision: Vision {
        overview: "Fast and reliable web platform".to_string(),
        goals: vec!["Handle 10k users".to_string()],
        target_users: vec!["Web developers".to_string()],
        success_criteria: vec!["< 100ms response time".to_string()],
    },
};

// Save the project
project_repo.create_project(&project).await?;

// Create a specification
let spec = spec_repo.create_spec(
    "my-web-app",
    "user_authentication",
    "User Authentication System",
    "OAuth2 and JWT-based authentication"
).await?;

println!("Created project and specification: {}", spec.id);

§File System Structure

Projects are stored in ~/.foundry/ with the following structure:

~/.foundry/
├── project-name/
│   ├── project/
│   │   ├── metadata.json      # Project information
│   │   ├── tech-stack.md      # Technology stack
│   │   └── vision.md          # Business vision
│   └── specs/
│       └── 20240115_feature_name/
│           ├── metadata.json  # Specification metadata
│           ├── spec.md        # Specification content
│           ├── task-list.md   # Implementation tasks
│           └── notes.md       # Development notes

§MCP Tools

The server provides these MCP tools for AI assistants:

  • setup_project - Create a new project with tech stack and vision
  • create_spec - Create a new specification for a feature or requirement
  • load_spec - Load complete context for a specification
  • update_spec - Update tasks and notes in a specification

§Error Handling

The library uses a comprehensive error system with user-friendly messages:

use project_manager_mcp::{ProjectManagerError, Result};

fn handle_error(result: Result<()>) {
    match result {
        Ok(()) => println!("Success!"),
        Err(ProjectManagerError::NotFound { resource_type, identifier, .. }) => {
            println!("{} '{}' not found", resource_type, identifier);
        }
        Err(ProjectManagerError::Validation { field, value, reason }) => {
            println!("Invalid {}: '{}' - {}", field, value, reason);
        }
        Err(err) => println!("Error: {}", err.user_message()),
    }
}

§Features

  • Type-safe data models with comprehensive validation
  • Atomic file operations with backup and rollback support
  • Dependency tracking for tasks and specifications
  • Rich metadata with timestamps and status tracking
  • Markdown content support for specifications and notes
  • Unicode support for international development teams
  • Comprehensive error handling with user-friendly messages

Re-exports§

pub use errors::ProjectManagerError;
pub use errors::Result;
pub use filesystem::FileSystemManager;
pub use handlers::ProjectManagerHandler;
pub use models::Note;
pub use models::Project;
pub use models::Specification;
pub use models::Task;
pub use models::TaskList;
pub use models::TechStack;
pub use models::Vision;
pub use repository::ProjectRepository;
pub use repository::SpecificationRepository;

Modules§

cache
Caching system for frequently accessed data
cli
errors
Custom error types and error handling for the Project Manager MCP server
filesystem
File system operations and directory management
handlers
MCP tool implementations and server handlers
lazy
Lazy loading system for large data structures
models
Core data structures for the Project Manager MCP
profiling
Performance profiling utilities for the project manager
progress
Progress tracking for long-running operations
repository
Data access layer for projects and specifications
security
Security utilities for path sanitization and input validation
tools
MCP tool definitions using the rust-mcp-sdk macros
utils
Utility functions and helpers

Macros§

profile_async_operation
Convenience macro for timing async operations
profile_operation
Convenience macro for timing operations
track_progress
Convenience macro for tracking operation progress