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 storagefilesystem
- Safe file system operations and managementhandlers
- MCP tool implementations for the protocol interfaceerrors
- Comprehensive error types and handlingutils
- 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