diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb6d973..6e20456 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,19 @@ > Updated on 2025-07-23 by @KemingHe -Thank you for your interest in contributing! This document provides development setup instructions and guidelines. +Thank you for your interest in contributing! This guide covers development workflow and setup. -## πŸ› οΈ Development Setup +## πŸ”„ Contribution Workflow + +**Issue-first approach**: No issue, no PR. No PR, no merge. + +1. **Raise issue** - Bug report or feature request +2. **Get assigned** - Wait for maintainer assignment +3. **Create PR** - Link to assigned issue +4. **Review & approval** - Address feedback +5. **Merge** - Maintainer merges approved PR -**Transport**: Stdio only (MCP standard for local tools). +## πŸ› οΈ Development Setup ### Local Development @@ -16,19 +24,19 @@ git clone cd python-dep-manager-companion-mcp-server uv sync -# Run server locally +# Run server locally uv run --with fastmcp --with tantivy fastmcp run src/mcp_server.py # Build Docker image docker build -t py-dep-man-companion . ``` -### Local Testing with MCP Client +### Local Testing -For testing the server locally during development, add this configuration to your VSCode/Cursor `mcp.json`: +Add to your VSCode/Cursor's `mcp.json` for testing: ->[!IMPORTANT] -> Replace `/path/to/your/python-dependency-manager-companion-mcp-server` with the absolute path to your local repository. +> [!IMPORTANT] +> Replace `/path/to/your/repo` with your local repository path. ```json { @@ -37,16 +45,9 @@ For testing the server locally during development, add this configuration to you "py-dep-man-companion-native": { "command": "uv", "args": [ - "run", - "--directory", - "/path/to/your/python-dependency-manager-companion-mcp-server", - "--with", - "fastmcp>=2.10.5", - "--with", - "tantivy>=0.24.0", - "fastmcp", - "run", - "src/mcp_server.py" + "run", "--directory", "/path/to/your/repo", + "--with", "fastmcp>=2.10.5", "--with", "tantivy>=0.24.0", + "fastmcp", "run", "src/mcp_server.py" ] } } @@ -54,22 +55,20 @@ For testing the server locally during development, add this configuration to you } ``` -## πŸ“ Development Guidelines - -- Follow existing code style and structure -- Test your changes locally using the native configuration above -- Update documentation when adding new features -- Submit pull requests with clear descriptions of changes +## πŸ“ Development Standards -### Git Workflow & Branching +### Git Workflow -- **Branching pattern**: `type/feature-or-bug-scope/GitHubUsername` +- **Branching**: `type/feature-or-bug-scope/GitHubUsername` - **Types**: `feat`, `fix`, `docs`, `test`, `refactor`, `chore` +- **Commits**: Use `prompts/prompt-commit-msg-gen.md` for consistency + +### Quality Tools -### Prompts for AI-Assisted Development +Available templates and prompts for consistent contributions: > [!TIP] -> This project includes AI prompts and GitHub templates for consistent, high-quality contributions: +> Use these tools for consistent, high-quality contributions that reduce review cycles. ```plaintext .github/ @@ -77,7 +76,7 @@ For testing the server locally during development, add this configuration to you β”‚ β”œβ”€β”€ bug-report.md # Bug report template β”‚ └── feature-request.md # Feature request template └── PULL_REQUEST_TEMPLATE/ - └── pull_request_template.md # PR template with checklist + └── pull_request_template.md prompts/ β”œβ”€β”€ prompt-commit-msg-gen.md # Generate uniform commit messages @@ -86,12 +85,12 @@ prompts/ └── prompt-readme-gen.md # Maintain documentation standards ``` -## πŸ”„ Automated Updates +## πŸ€– Automated Systems -This repository includes automated workflows that: +The repository auto-updates weekly (Tuesday 6pm ET): -1. Update documentation weekly from official sources -2. Rebuild search indexes automatically -3. Publish multi-architecture Docker images +1. Syncs official documentation +2. Rebuilds search indexes +3. Publishes Docker images -See [.github/workflows/README.md](.github/workflows/README.md) for workflow details. +See [.github/workflows/README.md](.github/workflows/README.md) for technical details. diff --git a/README-dockerhub.md b/README-dockerhub.md new file mode 100644 index 0000000..6465af3 --- /dev/null +++ b/README-dockerhub.md @@ -0,0 +1,72 @@ +# Python Dependency Manager Companion MCP Server + +> README updated on 2025-07-23 by [@KemingHe](https://github.com/KemingHe) + +Official docs from `pip`, `poetry`, `uv`, and `conda` + automated weekly updates = zero maintenance overhead for developers using VSCode/Cursor with AI assistants. [[Demo]](https://www.loom.com/share/a80f6041dc374c07b95b2397ee4e8ca1?sid=1209cdce-7239-447e-8b20-49eae454cc9a) + +## πŸš€ Quick Start for Agentic IDEs + +**1. Pull latest Docker image**: + +```shell +docker pull keminghe/py-dep-man-companion:latest +``` + +**2. Add to your IDE's `mcp.json`**: + +```json +{ + "mcp": { + "servers": { + "python-deps": { + "command": "docker", + "args": ["run", "-i", "--rm", "keminghe/py-dep-man-companion:latest"] + } + } + } +} +``` + +**3. Query official docs directly in your AI chat** - guaranteed fresh from weekly automated updates. + +## πŸ”„ Auto-Update Architecture + +```plaintext +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ ⏰ Every Tuesday 6pm ET β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ πŸ“š Sync Official Docs β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ πŸ” Rebuild Search Index β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ 🐳 Publish Latest Image β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Zero maintenance**: Documentation automatically synced weekly from official sources. Docker `:latest` tag guarantees you always get current docs without manual updates. + +## 🀝 Contributing + +**Use as template**: [[Create from template]](https://github.com/new?template_name=python-dependency-manager-companion-mcp-server&template_owner=KemingHe) for your own MCP server projects. + +**Contribute back**: Fork and follow [CONTRIBUTING.md](https://github.com/KemingHe/python-dependency-manager-companion-mcp-server/blob/main/CONTRIBUTING.md) for development setup. + +## πŸ—ΊοΈ Roadmap + +- [ ] Add support for `pipenv`, `pdm`, `pixi` +- [ ] Add comprehensive tests with 100% coverage +- [ ] Add indexing support for PDF and CSV files + +## πŸ“„ License + +This project is licensed under the [MIT License](https://github.com/KemingHe/python-dependency-manager-companion-mcp-server/blob/main/LICENSE) - a permissive license that allows free use, modification, and distribution with attribution. + +## πŸ“ž Support + +Open a [GitHub issue](https://github.com/KemingHe/python-dependency-manager-companion-mcp-server/issues) for bug reports and feature requests. diff --git a/README.md b/README.md index 0e8800e..fb27970 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ docker pull keminghe/py-dep-man-companion:latest **Use as template**: [[Create from template]](https://github.com/new?template_name=python-dependency-manager-companion-mcp-server&template_owner=KemingHe) for your own MCP server projects. -**Contribute back**: Fork and see [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup. +**Contribute back**: Fork and follow [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup. ## πŸ”„ Auto-Update Architecture diff --git a/src/build_index.py b/src/build_index.py index cffc794..6d125a1 100644 --- a/src/build_index.py +++ b/src/build_index.py @@ -110,7 +110,7 @@ def find_markdown_files(assets_dir: Path) -> list[tuple[Path, str, Dict[str, Any def read_file_content(file_path: Path) -> str: """ Read file content with multiple encoding fallbacks. - + Note: This function is called only with paths from find_markdown_files(), which uses glob() to find files within the controlled ASSETS_DIR structure. The paths are generated by filesystem iteration, not user input. @@ -120,16 +120,16 @@ def read_file_content(file_path: Path) -> str: if not file_path.exists() or not file_path.is_file(): logger.warning(f"File does not exist or is not a regular file: {file_path}") return "" - + # Simple safety check: ensure resolved path is still within assets if not file_path.resolve().is_relative_to(ASSETS_DIR.resolve()): logger.error(f"File path outside assets directory: {file_path}") return "" - + except (OSError, ValueError) as e: logger.warning(f"Path validation failed for {file_path}: {e}") return "" - + encodings = ["utf-8", "utf-8-sig", "latin1", "cp1252"] for encoding in encodings: