MCP Test MCP

--- story_id: "0001" title: "Project setup and directory structure" created: "2025-10-09" status: done dependencies: [] estimated_complexity: "low" tags: ["setup", "infrastructure", "phase1"] - status: in-progress timestamp: 2025-10-09T17:05:12Z - status: ready-for-review timestamp: 2025-10-09T17:07:50Z - status: ready-for-review timestamp: 2025-10-09T20:24:17Z - status: done timestamp: 2025-10-09T20:28:42Z --- # Story 0001: Project setup and directory structure ## Description Create the initial project structure for mcp-test-mcp with proper Python packaging configuration. This includes setting up pyproject.toml, directory structure, virtual environment configuration, and basic project files. ## Acceptance Criteria - [x] `pyproject.toml` created with FastMCP v2, Pydantic v2, and pytest dependencies - [x] Directory structure created following standard layout: - `src/mcp_test_mcp/` (source code) - `tests/` (test files) - `docs/` (documentation) - [x] `.gitignore` configured for Python projects - [x] `LICENSE` file added (MIT or Apache 2.0) - [x] Virtual environment setup instructions documented - [x] Package installable with `pip install -e .` - [x] Entry point configured for `python -m mcp_test_mcp` ## Technical Notes **pyproject.toml key sections:** - FastMCP v2 (latest version via PyPI search) - Pydantic v2 - Python 3.11+ requirement - Optional dev dependencies: pytest, pytest-asyncio, pytest-cov, black, ruff, mypy **Entry point:** ```toml [project.scripts] mcp-test-mcp = "mcp_test_mcp.__main__:main" ``` ## AI Directives **IMPORTANT**: As you work through this story, please mark checklist items as complete `[x]` as you finish them. This ensures that if we need to pause and resume work, we have a clear record of progress. Update the `status` field in the frontmatter when moving between stages (in-progress, ready-for-review, done, blocked). Always search PyPI for current package versions rather than using training data versions. ## Implementation Map for Story 0001 ### Files Created/Modified - `/Users/wjackson/Developer/MCP/mcp_test_mcp/pyproject.toml` - Python project configuration with build system, dependencies, and tooling setup - `/Users/wjackson/Developer/MCP/mcp_test_mcp/.gitignore` - Git ignore patterns for Python projects - `/Users/wjackson/Developer/MCP/mcp_test_mcp/LICENSE` - Placeholder license file (needs license text) - `/Users/wjackson/Developer/MCP/mcp_test_mcp/README.md` - Project documentation template - `/Users/wjackson/Developer/MCP/mcp_test_mcp/src/mcp_test_mcp/__init__.py` - Package initialization and version info - `/Users/wjackson/Developer/MCP/mcp_test_mcp/src/mcp_test_mcp/__main__.py` - Entry point for module execution - `/Users/wjackson/Developer/MCP/mcp_test_mcp/tests/__init__.py` - Test suite initialization - `/Users/wjackson/Developer/MCP/mcp_test_mcp/docs/README.md` - Documentation structure placeholder ### Implementation Tasks (in suggested order) 1. **Package Version Resolution** (`pyproject.toml`) - Description: Search PyPI for current versions of FastMCP v2, Pydantic v2, pytest, and all dev dependencies - Dependencies: None - Notes: Must use latest stable versions, not training data versions. Use PyPI search or pip index commands. - TODO markers: Lines with "TODO: Add actual package versions after PyPI search" 2. **Project Metadata** (`pyproject.toml`, `LICENSE`, `README.md`) - Description: Fill in author information, URLs, and choose/add actual license text - Dependencies: None - Notes: Decision needed on MIT vs Apache 2.0. Repository URL depends on where code will be hosted. - TODO markers: - `pyproject.toml`: Lines 9-12, 24-26, 42-45 - `LICENSE`: Line 1-9 - `README.md`: Throughout file 3. **Main Entry Point Logic** (`src/mcp_test_mcp/__main__.py:main`) - Description: Implement argument parsing, configuration loading, MCP server initialization with FastMCP v2 - Dependencies: FastMCP v2 package versions (Task 1) - Notes: Should include logging setup, graceful shutdown, error handling. Needs FastMCP v2 API documentation. - TODO markers: Lines 18-65 4. **Package Public API** (`src/mcp_test_mcp/__init__.py`) - Description: Define and expose main package APIs, configure __all__ exports - Dependencies: Core MCP server implementation (Task 3) - Notes: Version management could use importlib.metadata for dynamic version reading - TODO markers: Lines 3-6, 8-13, 15-18 5. **README Documentation** (`README.md`) - Description: Fill in comprehensive project description, features, usage examples, badges - Dependencies: Main implementation (Task 3) to provide accurate examples - Notes: Should include working code examples, actual configuration options, real CLI usage - TODO markers: Throughout file (lines 3, 9-12, 15-18, 21-23, 28-34, 41-50, 58-61, 68-79, 92-98, 102-104, 108-110, 114-116, 120-122) 6. **Additional Documentation** (`docs/` directory) - Description: Create architecture.md, api.md, development.md, deployment.md, configuration.md files - Dependencies: Full implementation understanding (all previous tasks) - Notes: Can be created incrementally as features are implemented - TODO markers: `docs/README.md` lines 6-12 7. **Test Fixtures and Utilities** (`tests/__init__.py`) - Description: Add shared pytest fixtures, test configuration, helper functions - Dependencies: Understanding of what needs to be tested (Task 3-4) - Notes: Should include fixtures for MCP server instance, mock configurations, test data - TODO markers: Lines 3-11 ### Testing Tasks After implementation, verify: - `pytest` runs without errors (even with no tests initially) - `pip install -e .` successfully installs the package - `mcp-test-mcp` command is available after installation - `python -m mcp_test_mcp` executes (even if not fully implemented) - `black`, `ruff`, and `mypy` can run against the codebase - All tooling configuration in `pyproject.toml` is valid ### Critical Implementation Notes 1. **FastMCP v2 API**: Implementation agent MUST consult FastMCP v2 documentation for correct API usage, especially: - Server initialization pattern - Tool/resource/prompt registration - Transport configuration (STDIO vs HTTP streamable-http) - Async/await patterns 2. **Type Hints**: All functions should have complete type hints as per mypy configuration 3. **Error Handling**: Main entry point should catch and log errors gracefully, returning appropriate exit codes 4. **Configuration**: Consider whether configuration should be file-based (YAML/TOML), environment variables, or CLI arguments 5. **Logging**: Use Python's standard logging module with appropriate log levels ### Scaffold Completion Status - [x] All directory structure created - [x] All stub files created with appropriate TODO comments - [x] Entry points configured in pyproject.toml - [x] Development tooling configured (pytest, black, ruff, mypy) - [x] Git ignore patterns set up - [x] Implementation guidance documented - [x] Implementation map appended to user story