Skip to content

Commit bbdae36

Browse files
KemingHeKemingHe
authored
feat(init): establish project infrastructure with AI-less automation workflow (#1)
* feat(init): establish project infrastructure with AI-less automation workflow CHANGES - Initialize GitHub DevOps infrastructure with issue/PR templates - Create modular automation system for weekly doc updates (pip, poetry, uv, conda) - Add comprehensive README with Docker setup and development guide - Create prompt engineering system for AI-assisted development - Configure security-hardened workflows with commit signing IMPACT - Foundation for simple, cost-effective documentation automation - AI-less design using Tantivy full-text search (no expensive embeddings) - Weekly automated updates with streamlined contributor experience TECHNICAL NOTES - Sparse-checkout efficiency with pinned action hashes for security - TDD-ready workflows with github-actions[bot] signed commits - Modular architecture optimized for AI pair programming * fix(auto-update-docs.yml): improve file copy command also use idiomatic `workflow_call: {}` when no params
1 parent d69ada9 commit bbdae36

File tree

16 files changed

+565
-4
lines changed

16 files changed

+565
-4
lines changed

‎.github/ISSUE_TEMPLATE/bug-report.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Bug report
3+
about: Submit a bug report to notify our team
4+
title: '🐛 bug(component): brief description'
5+
labels: 'bug, help wanted'
6+
7+
---
8+
9+
### 🐛 What happened?
10+
11+
**Expected:** [What should happen]
12+
**Actual:** [What actually happened]
13+
14+
### 🔄 Steps to Reproduce
15+
16+
1. [First step to reproduce]
17+
2. [Second step to reproduce]
18+
3. [Third step where error occurs]
19+
20+
Walkthrough recording: [Loom link or video]
21+
22+
### 🌍 Environment
23+
24+
- OS: [e.g. macOS 14.0]
25+
- Browser: [e.g. Chrome 120] (if applicable)
26+
- Version: [e.g. v1.0.0]

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
blank_issues_enabled: false

‎.github/ISSUE_TEMPLATE/feature-request.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Feature request
3+
about: Suggest a new feature or enhancement
4+
title: '✨ feat(component): brief description'
5+
labels: 'enhancement, help wanted'
6+
7+
---
8+
9+
### 🎯 Problem
10+
11+
[Description of the problem or limitation this addresses]
12+
13+
### 💡 Proposed Solution
14+
15+
[Description of the desired feature or enhancement]
16+
17+
### 🤔 Alternatives Considered
18+
19+
[Other approaches considered, if any] (optional)

‎.github/PULL_REQUEST_TEMPLATE/pull_request_template.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: Pull Request
3+
about: Submit a pull request for review
4+
title: '🔄 type(scope): brief description'
5+
6+
---
7+
8+
[Brief description of changes and purpose]
9+
10+
Closes #[issue-number]
11+
12+
> [!WARNING]
13+
>
14+
> [Any merge requirements or dependencies]
15+
16+
### 🎯 Key Features
17+
18+
- **[Feature name]:** [Description of functionality or change]
19+
20+
### 💼 Business Impact
21+
22+
- **[Impact area]:** [How this benefits users or business]
23+
24+
### 🔧 Technical Highlights
25+
26+
- **[Technical aspect]:** [Implementation details or improvements]
27+
28+
---

‎.github/workflows/auto-update-docs.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Update Documentation
2+
3+
on:
4+
workflow_call: {}
5+
workflow_dispatch: {} # Manual trigger for testing
6+
7+
concurrency:
8+
group: update-docs
9+
cancel-in-progress: true
10+
11+
jobs:
12+
update-docs:
13+
name: Update ${{ matrix.manager }} docs
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: write
17+
strategy:
18+
max-parallel: 1 # Prevent commit conflicts
19+
matrix:
20+
include:
21+
- manager: pip
22+
repo: pypa/pip
23+
docs_path: docs
24+
target_dir: src/assets/pip
25+
- manager: poetry
26+
repo: python-poetry/poetry
27+
docs_path: docs
28+
target_dir: src/assets/poetry
29+
- manager: uv
30+
repo: astral-sh/uv
31+
docs_path: docs
32+
target_dir: src/assets/uv
33+
- manager: conda
34+
repo: conda/conda
35+
docs_path: docs
36+
target_dir: src/assets/conda
37+
38+
steps:
39+
- name: Checkout main repo
40+
uses: actions/checkout@v4
41+
42+
- name: Checkout ${{ matrix.manager }} docs
43+
uses: actions/checkout@v4
44+
with:
45+
repository: ${{ matrix.repo }}
46+
sparse-checkout: |
47+
${{ matrix.docs_path }}
48+
path: temp-docs
49+
50+
- name: Copy documentation files
51+
run: |
52+
# Create target directory if not exist
53+
mkdir -p ${{ matrix.target_dir }}
54+
55+
# Copy docs and preserve structure with metadata
56+
cp -a temp-docs/${{ matrix.docs_path }}/* ${{ matrix.target_dir }}/
57+
58+
# Add metadata file with source info
59+
echo "source_repo: ${{ matrix.repo }}" > ${{ matrix.target_dir }}/_metadata.yml
60+
echo "docs_path: ${{ matrix.docs_path }}" >> ${{ matrix.target_dir }}/_metadata.yml
61+
echo "updated_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> ${{ matrix.target_dir }}/_metadata.yml
62+
echo "commit_sha: $(cd temp-docs && git rev-parse HEAD)" >> ${{ matrix.target_dir }}/_metadata.yml
63+
64+
- name: Auto commit changes to main
65+
# Pin 3rd-party action to v6.0.1 commit hash released on 2025-06-11 to prevent supply chain attacks
66+
uses: stefanzweifel/git-auto-commit-action@778341af668090896ca464160c2def5d1d1a3eb0
67+
with:
68+
commit_message: 'docs(src/assets/): update ${{ matrix.manager }} official documentation'
69+
commit_options: '--signoff'
70+
file_pattern: 'src/assets/${{ matrix.manager }}/*'
71+
disable_globbing: true
72+
status_options: '--untracked-files=no'

‎.github/workflows/auto-update.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Auto Update Orchestrator
2+
3+
on:
4+
schedule:
5+
# Tuesday 6pm ET (22:00 UTC, accounting for EST/EDT)
6+
- cron: '0 22 * * 2'
7+
workflow_dispatch: {} # Manual trigger for testing
8+
9+
jobs:
10+
update-docs:
11+
name: Update Documentation
12+
uses: ./.github/workflows/auto-update-docs.yml
13+
14+
# TODO: Add when implemented
15+
# update-index:
16+
# name: Update Search Index
17+
# needs: update-docs
18+
# uses: ./.github/workflows/auto-update-index.yml
19+
20+
# build-deploy:
21+
# name: Build and Deploy
22+
# needs: update-index
23+
# uses: ./.github/workflows/auto-build-and-deploy.yml

‎.gitignore‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,10 @@ nosetests.xml
4747
coverage.xml
4848
*.cover
4949
*.py.cover
50+
*.lcov
5051
.hypothesis/
5152
.pytest_cache/
53+
.nyc_output
5254
cover/
5355

5456
# Translations
@@ -137,6 +139,10 @@ celerybeat.pid
137139
# Environments
138140
.env
139141
.envrc
142+
.env.development.local
143+
.env.test.local
144+
.env.production.local
145+
.env.local
140146
.venv
141147
env/
142148
venv/
@@ -173,7 +179,7 @@ cython_debug/
173179
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
174180
# and can be added to the global gitignore or merged into this file. For a more nuclear
175181
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
176-
#.idea/
182+
.idea/
177183

178184
# Abstra
179185
# Abstra is an AI-powered process automation framework.
@@ -186,7 +192,11 @@ cython_debug/
186192
# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
187193
# and can be added to the global gitignore or merged into this file. However, if you prefer,
188194
# you could uncomment the following to ignore the entire vscode folder
189-
# .vscode/
195+
.vscode/*
196+
!.vscode/extensions.json
197+
198+
# Sublime Text
199+
*.sublime-workspace
190200

191201
# Ruff stuff:
192202
.ruff_cache/
@@ -205,3 +215,44 @@ cython_debug/
205215
marimo/_static/
206216
marimo/_lsp/
207217
__marimo__/
218+
219+
# OS and System Files
220+
# macOS - System files that store metadata, icons, and settings
221+
.DS_Store
222+
.DS_Store?
223+
._*
224+
.AppleDouble
225+
.LSOverride
226+
Icon?
227+
.Spotlight-V100
228+
.Trashes
229+
230+
# Windows - System-generated files and folders
231+
Thumbs.db
232+
Thumbs.db:encryptable
233+
ehthumbs.db
234+
ehthumbs_vista.db
235+
[Dd]esktop.ini
236+
$RECYCLE.BIN/
237+
*.lnk
238+
239+
# Linux - System and folder-specific files
240+
.directory
241+
.Trash-*
242+
243+
# Runtime data
244+
pids
245+
*.pid
246+
*.seed
247+
*.pid.lock
248+
249+
# Additional logs
250+
logs
251+
npm-debug.log*
252+
yarn-debug.log*
253+
yarn-error.log*
254+
lerna-debug.log*
255+
.pnpm-debug.log*
256+
257+
# Cache directories
258+
.parcel-cache

‎README.md‎

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,90 @@
1-
# python-dep-manager-companion-mcp-server
2-
A local Model Context Protocol (MCP) server that unifies the latest documentation for all Python dependency managers, making it instantly searchable from your agentic IDE.
1+
# Python Dependency Manager MCP Server
2+
3+
> Updated on 2025-07-15 by @KemingHe
4+
5+
Local MCP server providing unified search across Python dependency manager documentation.
6+
7+
## 📋 Overview
8+
9+
Unified search for pip, poetry, uv, and conda docs via Docker with weekly auto-updates. Built with FastMCP and Tantivy.
10+
11+
## 🚀 Getting Started
12+
13+
### Step 1: Pull Docker Image
14+
15+
```shell
16+
docker pull keminghe/py-dep-man-companion:latest
17+
```
18+
19+
### Step 2: Configure Your IDE
20+
21+
Add to VSCode User Settings (JSON):
22+
23+
```json
24+
{
25+
"mcp": {
26+
"servers": {
27+
"python-deps": {
28+
"command": "docker",
29+
"args": ["run", "-i", "--rm", "keminghe/py-dep-man-companion:latest"]
30+
}
31+
}
32+
}
33+
}
34+
```
35+
36+
### Step 3: Start Searching
37+
38+
Query latest and unified documentation across all supported Python dependency managers directly from your AI assistant.
39+
40+
## 📁 Project Structure
41+
42+
```plaintext
43+
python-dep-manager-companion-mcp-server/
44+
├── .github/workflows/
45+
│ ├── auto-update.yml # Orchestrator: Tuesday 6pm ET
46+
│ └── auto-update-docs.yml # Modular: Doc fetching workflow
47+
├── docs/ # Project documentation
48+
├── src/
49+
│ ├── server.py # FastMCP server implementation
50+
│ ├── index.py # Tantivy search engine
51+
│ └── assets/ # Local documentation files
52+
│ ├── pip/ # Pip documentation .md files
53+
│ ├── poetry/ # Poetry documentation .md files
54+
│ ├── uv/ # UV documentation .md files
55+
│ └── conda/ # Conda documentation .md files
56+
├── Dockerfile # Container build configuration
57+
└── pyproject.toml # Project dependencies and metadata
58+
```
59+
60+
## 🛠️ Development
61+
62+
**Transport Support**: Stdio (default) and HTTP modes following MCP standards.
63+
64+
**Environment Variables**:
65+
66+
- `TRANSPORT_MODE`: `stdio` or `http` (default: `stdio`)
67+
- `TRANSPORT_PORT`: HTTP server port (default: `8080`)
68+
- `TRANSPORT_HOST`: Host binding (default: `127.0.0.1`)
69+
70+
**Local Development**:
71+
72+
```shell
73+
# Clone and setup
74+
git clone <repo-url>
75+
cd python-dep-manager-companion-mcp-server
76+
uv sync
77+
78+
# Run server
79+
uv run python src/server.py stdio
80+
```
81+
82+
**Roadmap**: Adding support for pipenv, pdm, pixi, and additional Python package managers.
83+
84+
## 📄 License
85+
86+
This project is licensed under the [MIT License](./LICENSE) - a permissive license that allows free use, modification, and distribution with attribution.
87+
88+
## 📞 Support
89+
90+
Open GitHub issues for bug reports and feature requests. Weekly documentation updates run automatically every Tuesday at 6pm ET with signed commits by `github-actions[bot]`.

0 commit comments

Comments
 (0)