Codebase MCP Server

# Feature: Multi-Project Workspace Support **Feature Branch**: `008-multi-project-workspace` **Created**: 2025-10-12 **Status**: Draft **Input**: Multi-project workspace support for isolated codebase management ## Original User Description Users working on multiple codebases need to keep them isolated - searching one project should never return results from another project. Currently, the codebase-mcp server can only index and search a single codebase. Users need the ability to maintain multiple projects simultaneously without data contamination or complex manual database management. ## Execution Status - [X] User description parsed - [X] Key concepts extracted - [X] Ambiguities marked - [X] User scenarios defined - [X] Requirements generated - [X] Entities identified - [X] Review checklist passed --- ## User Scenarios & Testing ### Primary User Story A full-stack developer maintains separate codebases for frontend, backend, and shared libraries. When searching for authentication logic, they need to find only results relevant to their currently active project without manually managing separate database instances or complex configuration files. The system automatically isolates each project's indexed code and search results, ensuring zero cross-contamination. ### Primary Workflow: Multi-Project Development **Step-by-step user journey:** 1. Developer starts work on client-a project 2. System provides isolated workspace for client-a 3. Developer indexes client-a codebase 4. System stores client-a code in isolated workspace 5. Developer searches for "authentication logic" in client-a 6. System returns only client-a results, zero cross-contamination 7. Developer switches to client-b project 8. System switches to client-b isolated workspace 9. Developer searches for "authentication logic" in client-b 10. System returns only client-b results, different from client-a 11. Developer verifies no cross-contamination between projects 12. System confirms complete isolation via testing ### Alternative Path: Workflow Automation Integration **Automatic project detection:** **IF** workflow-mcp is available: 1. Developer does not specify project identifier 2. System queries workflow-mcp for active project 3. System uses active project context automatically 4. Developer continues without manual project specification **ELSE**: 1. System uses default project workspace 2. Developer continues with backward-compatible behavior ### Alternative Path: New Project Creation **First-time project setup:** 1. Developer specifies new project identifier for first time 2. System detects project workspace does not exist 3. System validates appropriate permissions exist 4. System creates isolated workspace automatically 5. Developer indexes first repository into new project 6. System confirms workspace ready for use ### Acceptance Scenarios 1. **Given** developer is working on project-a and has indexed its codebase, **When** developer searches for "authentication", **Then** system returns only results from project-a with zero results from other projects 2. **Given** developer switches from project-a to project-b, **When** developer performs the same search query, **Then** system returns completely different results specific to project-b 3. **Given** developer provides a new project identifier "client-xyz", **When** system detects no existing workspace for this identifier, **Then** system automatically creates isolated workspace without manual intervention 4. **Given** workflow-mcp integration is available, **When** developer performs indexing or search without specifying project, **Then** system automatically uses active project from workflow-mcp 5. **Given** workflow-mcp integration times out, **When** system detects timeout condition, **Then** system falls back to default workspace and logs timeout event 6. **Given** developer provides invalid project identifier "My_Project", **When** system validates the identifier, **Then** system rejects with clear message about lowercase alphanumeric with hyphen format ### Edge Cases #### Empty State - No Projects Yet - **What happens when**: First-time user with no existing projects - **System behavior**: Uses default project workspace automatically - **User experience**: Immediate productivity without setup, can create additional projects later #### Boundary Condition - Maximum Project Identifier Length - **What happens when**: Developer provides 50-character project identifier (maximum allowed) - **System behavior**: Accepts and creates workspace successfully - **User experience**: Valid input processed normally #### Boundary Condition - Exceeds Maximum Length - **What happens when**: Developer provides 51+ character project identifier - **System behavior**: Rejects with clear message: "Project identifier must be 50 characters or less" - **User experience**: Developer shortens identifier and retries successfully #### Error Scenario - Invalid Characters in Identifier - **What happens when**: Developer provides "My_Project" (uppercase and underscore) - **System behavior**: Rejects with message: "Project identifiers must be lowercase alphanumeric with hyphens only" - **User experience**: Developer corrects to "my-project" format and succeeds #### Error Scenario - Permission Denied - **What happens when**: System lacks permission to create new project workspace - **System behavior**: Displays error: "Cannot create project workspace - insufficient permissions. Contact administrator." - **User experience**: Developer escalates to administrator, who grants permissions, then developer retries successfully #### Error Scenario - Workflow Integration Timeout - **What happens when**: workflow-mcp query exceeds timeout threshold - **System behavior**: Logs timeout, falls back to default project workspace - **User experience**: Developer continues with default workspace, can manually specify project if needed #### Error Scenario - Workflow Integration Unavailable - **What happens when**: workflow-mcp server not accessible - **System behavior**: Detects unavailability, falls back to default project workspace - **User experience**: Developer continues with default workspace or manual specification #### Concurrent Operation - Simultaneous Project Creation - **What happens when**: Two developers create same project identifier simultaneously - **System behavior**: Handles race condition gracefully (first succeeds, second reuses existing workspace) - **User experience**: Both developers use same project workspace (intended behavior for collaboration) #### Security Scenario - SQL Injection Attempt - **What happens when**: Developer provides malicious project identifier: `"project'; DROP TABLE--"` - **System behavior**: Validation rejects before any database operations occur - **User experience**: System logs security event, developer must use valid identifier --- ## Requirements ### Functional Requirements - **FR-001**: System MUST accept optional project identifier parameter for indexing operations - **Acceptance Criteria**: Indexing operation accepts project identifier without error - **Traces to**: Primary Workflow step 3 - **FR-002**: System MUST accept optional project identifier parameter for search operations - **Acceptance Criteria**: Search operation accepts project identifier without error - **Traces to**: Primary Workflow step 5 - **FR-003**: System MUST provide default project workspace when no identifier specified - **Acceptance Criteria**: Operations without project identifier use consistent default workspace - **Traces to**: Alternative Path (workflow integration ELSE clause) - **FR-004**: System MUST validate project identifiers before use - **Acceptance Criteria**: Invalid identifiers rejected with clear error messages - **Traces to**: Edge Case (invalid characters) - **FR-005**: System MUST enforce lowercase alphanumeric with hyphen format for identifiers - **Acceptance Criteria**: Uppercase, underscore, spaces, special characters rejected - **Traces to**: Edge Case (invalid characters scenario) - **FR-006**: System MUST enforce maximum 50-character length for identifiers - **Acceptance Criteria**: Identifiers of 51+ characters rejected with helpful error - **Traces to**: Edge Case (exceeds maximum length) - **FR-007**: System MUST prevent identifiers starting or ending with hyphens - **Acceptance Criteria**: "-project" and "project-" rejected, "my-project" accepted - **Traces to**: Validation rules - **FR-008**: System MUST prevent consecutive hyphens in identifiers - **Acceptance Criteria**: "my--project" rejected, "my-project" accepted - **Traces to**: Validation rules - **FR-009**: System MUST create isolated workspace for each unique project identifier - **Acceptance Criteria**: Data indexed in project-a never appears in project-b searches - **Traces to**: Primary Workflow steps 4, 6, 10 - **FR-010**: System MUST automatically provision workspace on first use - **Acceptance Criteria**: New project identifier triggers workspace creation without manual steps - **Traces to**: Alternative Path (new project creation) - **FR-011**: System MUST validate required permissions before workspace creation - **Acceptance Criteria**: Permission check occurs before creation attempt, clear error if insufficient - **Traces to**: Edge Case (permission denied) - **FR-012**: System SHOULD query workflow-mcp for active project when available (workflow-mcp integration is optional but recommended for enhanced automation) - **Acceptance Criteria**: If workflow-mcp accessible, system retrieves active project context - **Traces to**: Alternative Path (workflow automation integration) - **FR-013**: System MUST gracefully handle workflow-mcp unavailability - **Acceptance Criteria**: Workflow-mcp timeout/unavailability falls back to default workspace without errors - **Traces to**: Edge Cases (timeout, unavailable) - **FR-014**: System MUST categorize workflow-mcp integration failures - **Acceptance Criteria**: Distinct error types (unavailable, timeout, invalid response) logged for troubleshooting - **Traces to**: Alternative Path (workflow integration ELSE clause) - **FR-015**: System SHOULD cache workflow-mcp responses temporarily (caching strategy is an implementation detail; local machine performance is adequate without prescriptive cache duration) - **Acceptance Criteria**: Repeated queries within short time window reuse cached result - **Traces to**: Persona 4 (workflow automation user) efficiency needs - **FR-016**: System MUST prevent security vulnerabilities via identifier validation - **Acceptance Criteria**: SQL injection attempts blocked, malicious identifiers rejected - **Traces to**: Edge Case (SQL injection attempt) - **FR-017**: System MUST maintain complete data isolation between projects - **Acceptance Criteria**: Integration test confirms zero cross-project data leakage - **Traces to**: Primary Workflow step 11, Persona 2 (consultant confidentiality) - **FR-018**: System MUST support backward compatibility for existing users - **Acceptance Criteria**: Existing usage without project identifiers continues working unchanged - **Traces to**: FR-003 (default workspace), business value (no breaking changes) ### Key Entities #### Entity: Project Workspace - **Purpose**: Represents an isolated environment for a single codebase or logical project grouping - **Lifecycle**: - Created: Automatically on first use of a new project identifier - Updated: Implicitly when repositories indexed or searches performed - Deleted: Future feature - workspace deletion requires explicit confirmation flag - **Key Attributes**: - **Identifier**: Unique string identifying the workspace (lowercase alphanumeric with hyphens, max 50 chars) - **Isolation Boundary**: Workspace stores all indexed repositories and search indices independently - **Creation Timestamp**: When workspace first created (for future archival features) - **Business Invariants**: - Identifier must remain immutable after creation (no renaming) - Complete isolation guarantee: no data sharing between workspaces - Default workspace always available for backward compatibility #### Entity: Project Identifier - **Purpose**: Validated string that uniquely names a project workspace - **Lifecycle**: - Created: User provides identifier in indexing or search operation - Updated: Never (immutable) - Deleted: N/A (identifiers persist with workspaces) - **Key Attributes**: - **Format**: Lowercase alphanumeric characters with hyphens only - **Length**: 1-50 characters inclusive - **Constraints**: Cannot start/end with hyphen, no consecutive hyphens - **Business Invariants**: - Must pass validation before any operations - Same identifier always resolves to same workspace - Validation prevents security vulnerabilities #### Entity: Workflow Integration Context (Optional) - **Purpose**: Represents active project context from workflow-mcp when available - **Lifecycle**: - Created: Queried from workflow-mcp on demand - Updated: Cached temporarily (recommended 1 minute) - Deleted: Cache expires after TTL - **Key Attributes**: - **Active Project**: Current project identifier from workflow-mcp - **Cache Timestamp**: When value retrieved (for expiration calculation) - **Status**: Success, unavailable, timeout, invalid response - **Business Invariants**: - Graceful degradation required (system works without workflow-mcp) - Cache must not serve stale values beyond TTL - Errors must not block user operations --- ## Success Criteria ### Quantitative Metrics - **Isolation Guarantee**: 100% of cross-project searches return zero results from other projects (verified via integration tests) - **Validation Effectiveness**: 100% of invalid project identifiers rejected before operations - **Permission Detection**: System detects insufficient permissions before failed operations in 100% of cases - **Workflow Integration Success Rate**: When workflow-mcp available, system retrieves active project in 100% of attempts (excluding timeouts) - **Fallback Reliability**: System falls back to default workspace in 100% of workflow-mcp failure scenarios - **Security Coverage**: 100% of SQL injection test cases blocked by validation ### Qualitative Measures - **User Workflow Simplification**: Full-stack developers complete project switches without manual database operations - **Consultant Confidence**: Consultants trust complete isolation for client confidentiality - **Manager Satisfaction**: Engineering managers achieve multi-team support with single infrastructure instance - **Automation Seamlessness**: Workflow-mcp users experience automatic project detection when available - **Error Clarity**: Users understand validation errors and can correct identifiers without support tickets --- ## Edge Cases & Error Handling **Empty States** - See "Edge Case Workflows: Empty State - No Projects Yet" - Behavior: System uses default workspace, enables immediate productivity **Boundary Conditions** - See "Edge Case Workflows: Maximum Project Identifier Length" - See "Edge Case Workflows: Exceeds Maximum Length" - Behavior: Clear validation messages guide users to valid formats **Error Scenarios** - See "Edge Case Workflows: Invalid Characters in Identifier" - See "Edge Case Workflows: Permission Denied" - See "Edge Case Workflows: Workflow Integration Timeout" - See "Edge Case Workflows: Workflow Integration Unavailable" - Behavior: Specific error messages with recovery guidance **Permission Denials** - See "Edge Case Workflows: Permission Denied" - Behavior: Early detection with administrator escalation guidance **Concurrent Operations** - See "Edge Case Workflows: Simultaneous Project Creation" - Behavior: Graceful race condition handling, idempotent operations **Security Scenarios** - See "Edge Case Workflows: SQL Injection Attempt" - Behavior: Validation blocks attacks before database operations, security logging --- ## Non-Goals (Explicitly Out of Scope) ### Not Included in This Phase - Connection pooling optimization (deferred to Phase 04) - Performance tuning and benchmarking (deferred to Phase 06) - Documentation updates and migration guides (deferred to Phase 05) - Production deployment procedures (deferred to Phase 07) ### Explicitly NOT Doing - Cross-project search (searching multiple projects simultaneously) - Project management UI or CLI commands - Project deletion, archival, or lifecycle management features - Project configuration storage or metadata - Project-specific settings or preferences - Project sharing or permissions between users - Project import/export capabilities - Project statistics or analytics - Historical project data or versioning - Automatic project detection from Git repository names - Project templates or initialization wizards ### Future Considerations (Not This Phase) - Project workspace cleanup and archival policies - Cross-project analytics and reporting - Team collaboration features (shared projects) - Project-specific search configuration - Project metadata storage (description, tags, owner) - Project access control and permissions --- ## User Personas ### Persona 1: Full-Stack Developer (Primary) - Manages 3-5 codebases simultaneously (frontend, backend, shared libraries) - Switches between projects multiple times daily - Needs instant context switching without cross-contamination - Technical proficiency: High ### Persona 2: Consultant with Multiple Clients - Maintains 5-10 client projects simultaneously - Requires strict isolation for confidentiality - Needs quick project switching during client calls - Technical proficiency: Medium-High ### Persona 3: Engineering Manager - Oversees multiple team projects - Reviews code across different repositories - Concerned with infrastructure costs and team efficiency - Technical proficiency: Medium ### Persona 4: Workflow Automation User - Uses workflow-mcp for project management - Expects automatic project detection - Values seamless integration between tools - Technical proficiency: Medium --- ## Business Value - **Enables Multi-Tenant Usage**: Multiple users/teams share infrastructure without conflicts - **Reduces Infrastructure Costs**: Single server instance supports multiple projects - **Simplifies User Workflow**: No manual database management or complex configuration - **Supports Modern Development**: Context switching for multi-repo workflows - **Foundation for Future Features**: Enables project-specific settings, analytics, collaboration --- ## Dependencies & Assumptions ### Dependencies - Phase 02 completion (baseline system must be functional) - workflow-mcp server (optional integration, not required) ### Assumptions - Users understand project isolation concept - Default workspace behavior is acceptable for backward compatibility - 50-character identifier limit is sufficient for real-world use - 1-minute cache duration appropriate for workflow integration - Users willing to adopt project identifier parameter in tool calls --- ## Review & Acceptance Checklist ### Content Quality - [X] No implementation details (languages, frameworks, APIs) - [X] Focused on user value and business needs - [X] Written for non-technical stakeholders - [X] All mandatory sections completed - [X] Terminology consistent throughout ### Requirement Completeness - [X] Maximum 3 [NEEDS CLARIFICATION] markers (3 present with justification) - [X] All requirements testable and unambiguous - [X] User types and permissions explicitly defined - [X] Edge cases and error scenarios included - [X] Success criteria measurable and specific - [X] Each requirement traces to user story - [X] Non-functional requirements captured (isolation, security) ### Scope Clarity - [X] Feature boundaries clearly defined - [X] Out-of-scope items explicitly listed - [X] Dependencies identified (Phase 02 completion) - [X] Integration points specified (workflow-mcp optional) - [X] Assumptions documented ### Constitutional Compliance - [X] Aligns with Simplicity Over Features principle (focused on multi-project only) - [X] Follows Local-First Architecture (no cloud dependencies introduced) - [X] Respects Protocol Compliance (MCP tool parameter additions only) - [X] Adheres to Production Quality (comprehensive error handling specified) - [X] Compatible with Test-Driven Development (testable requirements) --- ## Clarifications Section **✅ Clarifications Resolved (2025-10-12)** **Resolved Clarification Items (3):** 1. **FR-012**: Should workflow-mcp integration be mandatory or optional? - **RESOLVED**: Integration is optional but recommended for enhanced automation - **Context**: Optional enables standalone operation while providing automation for workflow-mcp users - **Impact**: Architecture design supports graceful fallback, testing scope includes both integrated and standalone modes 2. **FR-015**: What cache duration balances freshness vs. efficiency? - **RESOLVED**: Caching strategy is an implementation detail; local machine performance is adequate without prescriptive cache duration - **Context**: System runs on local machine where performance concerns are minimal - **Impact**: Implementation has flexibility to optimize based on observed performance characteristics 3. **Entity: Project Workspace (Deletion)**: How should users remove old project workspaces? - **RESOLVED**: Future feature - workspace deletion requires explicit confirmation flag - **Context**: Deletion functionality deferred to future management features with safety requirements - **Impact**: Scope boundaries clarified, deletion API planned for future phase with mandatory confirmation