diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ef005fd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,119 @@ +# Contributing to github-mcp + +Thanks for your interest in contributing! This guide covers everything you need to get started. + +## Getting Started + +### Prerequisites + +- Node.js >= 20 +- npm +- A GitHub account (for OAuth testing) + +### Development Setup + +```bash +git clone https://github.com/ldraney/github-mcp.git +cd github-mcp +npm install +npm run build +``` + +### Running Locally + +```bash +# With OAuth (will prompt for browser auth) +npm start + +# With a personal access token +GITHUB_TOKEN=ghp_xxx npm start + +# Watch mode for development +npm run dev +``` + +## Development Commands + +| Command | Description | +|---------|-------------| +| `npm run build` | Compile TypeScript | +| `npm run dev` | Watch mode with tsx | +| `npm test` | Run tests | +| `npm run lint` | Run ESLint | +| `npm run typecheck` | Type check without emitting | + +## Code Style + +- TypeScript strict mode +- ES2022 modules +- Async/await over callbacks +- Descriptive error messages +- JSDoc for public APIs + +## Making Changes + +### 1. Open an Issue First + +All work should be tracked by a GitHub issue. Open one before starting work so we can discuss the approach. + +### 2. Branch from main + +```bash +git checkout -b -short-description +``` + +### 3. Make Your Changes + +- Keep changes focused and minimal +- Follow existing patterns in the codebase +- Add tests where applicable + +### 4. Verify Your Work + +```bash +npm run typecheck +npm run build +npm run lint +``` + +### 5. Submit a Pull Request + +- Fill out the PR template completely +- Link the related issue with `Closes #` +- Describe what changed and why + +## Project Structure + +``` +src/ +├── index.ts # CLI entry point (commander) +├── server.ts # MCP server setup +├── auth/ # OAuth Device Flow + keychain storage +├── tools/ # Tool generation and category handlers +├── resources/ # MCP resources (webhook events) +└── webhooks/ # smee.io client + event queue +``` + +### Adding a New Tool Category + +1. Create `src/tools/categories/.ts` +2. Export tool definitions following the existing pattern +3. Register in `src/tools/generator.ts` + +### Adding a New Webhook Handler + +1. Add event type to `src/webhooks/event-queue.ts` +2. Create resource in `src/resources/webhooks.ts` + +## Reporting Bugs + +Use the GitHub issue tracker. Include: + +- Steps to reproduce +- Expected vs actual behavior +- Node.js version and OS +- Relevant error output + +## Questions? + +Open an issue or start a discussion on the repo. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d95daa7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 ldraney + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 1e4c0c7..418f4cd 100644 --- a/README.md +++ b/README.md @@ -163,6 +163,11 @@ npm run build npm start ``` +## Contact + +- [LinkedIn](https://www.linkedin.com/in/lucas-draney-904457133/) +- [GitHub Issues](https://github.com/ldraney/github-mcp/issues) + ## License MIT diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1ce05c1 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,44 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| 0.2.x | Yes | +| < 0.2 | No | + +## How Authentication Works + +This project handles GitHub authentication securely: + +- **OAuth Device Flow** - Tokens are obtained via GitHub's standard OAuth flow, not stored in config files +- **OS Keychain** - Tokens are stored in your operating system's credential manager (macOS Keychain, Windows Credential Vault, Linux libsecret) via `@napi-rs/keyring` +- **Environment variable fallback** - `GITHUB_TOKEN` can be used but is the user's responsibility to secure + +No credentials are ever written to disk as plaintext files. + +## Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly: + +1. **Do not** open a public GitHub issue +2. Contact the maintainer directly via [LinkedIn](https://www.linkedin.com/in/lucas-draney-904457133/) +3. Include a description of the vulnerability, steps to reproduce, and potential impact + +You should receive a response within 72 hours. Once confirmed, a fix will be prioritized and released as a patch version. + +## Scope + +The following are in scope for security reports: + +- Token leakage or exposure +- Authentication bypass +- Injection vulnerabilities in tool input handling +- Unauthorized access to GitHub API resources +- Webhook event data exposure + +The following are out of scope: + +- Vulnerabilities in GitHub's API itself +- Issues requiring physical access to the machine +- Social engineering attacks diff --git a/docs/architecture.html b/docs/architecture.html index 995a784..1b38c35 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -341,7 +341,8 @@

Error Handling Strategy

GitHub · npm · - Issues + Issues · + LinkedIn

Built by @ldraney

diff --git a/docs/guide.html b/docs/guide.html index eaaf050..4f3291b 100644 --- a/docs/guide.html +++ b/docs/guide.html @@ -435,7 +435,8 @@

Links

GitHub · npm · - Issues + Issues · + LinkedIn

Built by @ldraney

diff --git a/docs/index.html b/docs/index.html index b907386..26acd4d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -267,7 +267,8 @@

Built-in Workflows

GitHub · npm · - Issues + Issues · + LinkedIn

Built by @ldraney

diff --git a/docs/roadmap.html b/docs/roadmap.html index 0f17826..e13fcbc 100644 --- a/docs/roadmap.html +++ b/docs/roadmap.html @@ -296,7 +296,8 @@

Presets are code, not config

GitHub · npm · - Issues + Issues · + LinkedIn

Built by @ldraney

diff --git a/docs/user-story.html b/docs/user-story.html index aac7816..5a7f0c7 100644 --- a/docs/user-story.html +++ b/docs/user-story.html @@ -258,7 +258,8 @@

Error Handling

GitHub · npm · - Issues + Issues · + LinkedIn

Built by @ldraney