|
| 1 | +# Contributing to MCP Local RAG |
| 2 | + |
| 3 | +Contributions welcome! This guide covers what you need to get started. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Node.js >= 20 |
| 8 | +- [pnpm](https://pnpm.io/) |
| 9 | + |
| 10 | +## Setup |
| 11 | + |
| 12 | +```bash |
| 13 | +git clone https://github.com/shinpr/mcp-local-rag.git |
| 14 | +cd mcp-local-rag |
| 15 | +pnpm install |
| 16 | +``` |
| 17 | + |
| 18 | +The embedding model (~90MB) downloads on first test/run. |
| 19 | + |
| 20 | +## Quality Checks |
| 21 | + |
| 22 | +All PRs must pass the full quality check, which mirrors CI: |
| 23 | + |
| 24 | +```bash |
| 25 | +pnpm run check:all |
| 26 | +``` |
| 27 | + |
| 28 | +This runs the following in order: |
| 29 | + |
| 30 | +| Step | Command | What it checks | |
| 31 | +|------|---------|----------------| |
| 32 | +| Biome check | `pnpm run check` | Lint + format combined | |
| 33 | +| Lint | `pnpm run lint` | Code quality rules | |
| 34 | +| Format | `pnpm run format:check` | Code formatting | |
| 35 | +| Unused exports | `pnpm run check:unused` | No dead exports | |
| 36 | +| Circular deps | `pnpm run check:deps` | No circular dependencies | |
| 37 | +| Build | `pnpm run build` | TypeScript compilation | |
| 38 | +| Test | `pnpm run test` | All tests pass | |
| 39 | + |
| 40 | +Fix lint/format issues automatically: |
| 41 | + |
| 42 | +```bash |
| 43 | +pnpm run check:fix |
| 44 | +``` |
| 45 | + |
| 46 | +## PR Requirements |
| 47 | + |
| 48 | +Before submitting a pull request: |
| 49 | + |
| 50 | +1. **Add tests** for new features and bug fixes |
| 51 | +2. **Run `pnpm run check:all`** and ensure everything passes |
| 52 | +3. **Update documentation** if behavior changes |
| 53 | +4. **Keep commits focused** — one logical change per PR |
| 54 | + |
| 55 | +## What We Look For |
| 56 | + |
| 57 | +This project's development standards — testing strategy, error handling, code organization, etc. — are documented in [claude-code-workflows/skills](https://github.com/shinpr/claude-code-workflows/tree/main/skills). |
| 58 | + |
| 59 | +We share this upfront so you know what to expect in review, not after. You don't need to memorize it, but if review feedback feels unexpected, that's where it comes from. |
| 60 | + |
| 61 | +## Project Structure |
| 62 | + |
| 63 | +``` |
| 64 | +src/ |
| 65 | + index.ts # Entry point |
| 66 | + server/ # MCP tool handlers |
| 67 | + parser/ # Document parsing (PDF, DOCX, TXT, Markdown, HTML) |
| 68 | + chunker/ # Semantic text chunking |
| 69 | + embedder/ # Transformers.js embeddings |
| 70 | + vectordb/ # LanceDB operations |
| 71 | + __tests__/ # Test suites |
| 72 | +``` |
| 73 | + |
| 74 | +## License |
| 75 | + |
| 76 | +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). |
0 commit comments