v2.0.0 - Modular Architecture & Code Quality

Release v2.0.0 - Modular Architecture & Code Quality

Release Date: December 29, 2024

🎉 Major Version Release

This is a major release that introduces a complete architectural refactor, moving from a monolithic codebase to a clean, modular structure. This release significantly improves maintainability, developer experience, and sets the foundation for future growth.

⚠️ Breaking Changes

Entry Point Moved

The entry point has moved from index.js to src/index.js:

Before:

{
  "main": "index.js"
}

After:

{
  "main": "src/index.js"
}

Action Required:

• Update MCP server configurations to use src/index.js
• The old monolithic index.js has been completely removed

✨ What's New

Modular Architecture

The codebase has been completely reorganized into a clean, modular structure:

src/
├── index.js          # Minimal entry point (15 lines)
├── server.js         # Main ProjectMCPServer class
├── lib/              # Shared utilities
│   ├── constants.js
│   ├── dates.js
│   ├── files.js
│   ├── search.js
│   └── tasks.js
├── tools/            # Tool handlers
│   ├── search.js
│   ├── project-files.js
│   ├── tasks.js
│   ├── backlog.js
│   └── lint.js
├── prompts/          # MCP prompts
│   ├── definitions.js
│   └── index.js
└── resources/        # Resource handlers
    └── index.js

Benefits:

• Maintainability: Each module has a single responsibility
• Testability: Easier to test individual components
• Scalability: Simple to add new tools or features
• Readability: Code is organized and easy to navigate

Code Quality Improvements

• Prettier Integration: Consistent code formatting across the entire codebase
• Format Scripts: npm run format and npm run format:check for easy formatting
• 37 files formatted: All JavaScript, Markdown, and JSON files now follow consistent style

ToolSDK Registry Support

• Added toolsdk-registry.json configuration for discoverability
• Ready for submission to the ToolSDK MCP Registry
• All 22 tools and 8 prompts documented

Documentation Organization

• Release notes moved to docs/releases/ directory
• Cleaner root directory structure
• Better organization of project documentation

📊 Statistics

• Code Reduction: 4019 lines → 15 lines (entry point)
• Files Organized: 20 modular files vs 1 monolithic file
• Formatting: 37 files formatted with Prettier
• Maintainability: Significantly improved code organization

🔄 Migration Guide

For MCP Server Users

1. Update your MCP configuration:

   {
     "mcpServers": {
       "project-mcp": {
         "command": "node",
         "args": ["path/to/project-mcp/src/index.js"]
       }
     }
   }

2. No API changes: All tools and prompts work exactly the same

3. No breaking changes to functionality: Only the file structure changed

For Developers

1. Import paths remain the same: Internal imports are unchanged
2. New structure: Familiarize yourself with the modular organization
3. Formatting: Run npm run format before committing

🚀 What's Next

This release sets the foundation for:

• Easier feature additions
• Better testing infrastructure
• Improved documentation
• Enhanced developer experience

📝 Full Changelog

See CHANGELOG.md for detailed changes.

🙏 Thank You

Thank you for using project-mcp! This major refactor was done to improve the long-term maintainability and developer experience of the project.

---

Upgrade Path: npm install project-mcp@2.0.0

Documentation: README.md

v1.0.0 - First Stable Release

Release v1.0.0 - First Stable Release

Release Date: December 29, 2024

🎉 First Stable Release

This is the first stable release of project-mcp, an intent-based MCP server for project documentation search. This release establishes the standard for AI agent documentation search with zero configuration required.

✨ Key Features

Intent-Based Search

• Maps natural language queries to the right sources automatically
• No configuration needed - understands intent, not just directory names
• Smart detection of user intent from query keywords

Multi-Source Indexing

• Searches .project/ directory (operational truth)
• Searches root-level markdown files (README.md, DEVELOPMENT.md, etc.)
• Searches docs/ directory (reference documentation)

Zero Configuration

• Automatically discovers and indexes documentation
• Works out of the box with standard project structure
• Customizable via environment variables if needed

🛠️ Available Tools

• search_project - Intent-based search across all sources
• search_docs - Search reference documentation only
• get_doc - Get full file content
• list_docs - List all documentation files
• get_doc_structure - Get directory structure

📚 Documentation

• Comprehensive README with examples and architecture diagrams
• Quick Start guide for 5-minute setup
• Documentation templates for all file types
• Best practices and structure guides

🎯 Intent Mapping

User Says	Searches
"project" / "the project"	.project/ + root files + docs/
"docs" / "documentation"	Only docs/
"plan" / "todos" / "roadmap" / "status"	Only .project/

📦 Installation

npm install project-mcp

⚙️ Configuration

Add to .mcp.json:

{
	"mcpServers": {
		"project": {
			"command": "npx",
			"args": ["-y", "project-mcp"]
		}
	}
}

🔧 Technical Details

• Node.js: >=18.0.0
• Dependencies:
  • @modelcontextprotocol/sdk: ^1.0.4
  • fuse.js: ^7.0.0 (fuzzy search)
  • gray-matter: ^4.0.3 (frontmatter parsing)
  • mime-types: ^2.1.35

📝 What's Included

• Core MCP server implementation
• Intent-based search engine
• Fuzzy search with relevance scoring
• Automatic documentation indexing
• Comprehensive documentation
• Quick Start guide
• Documentation templates
• GitHub topics guide

🌟 Why This Matters

Before project-mcp:

• Agents had to guess which directory to search
• Users had to know directory structure
• Manual mapping required for each project
• No standard for organizing project knowledge

With project-mcp:

• Natural language just works
• Intent maps to sources automatically
• Standard contract across all projects
• Zero configuration needed
• Clear separation: operational vs. reference truth

🚀 Getting Started

1. Install: npm install project-mcp
2. Configure: Add to .mcp.json (see above)
3. Create .project/index.md contract file
4. Organize your documentation
5. Restart your MCP client
6. Start searching!

See QUICK_START.md for detailed setup instructions.

📖 Documentation

• README.md - Comprehensive documentation
• QUICK_START.md - 5-minute setup guide
• EXAMPLES.md - Usage examples
• .github/README_TEMPLATES.md - Documentation templates

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

This project establishes a new standard for project documentation organization and AI agent search capabilities. Thank you to the MCP community for inspiration and feedback.

---

Made for AI agents. Built for developers. Standard for everyone.