README.md•4.53 kB
# GitHub Integration Hub
> Built by Cristian to demonstrate OAuth orchestration, secure token storage, SDK/CLI tooling, and MCP servers in TypeScript.
## Why this project exists
I wanted a hands-on showcase proving I can:
- Design an OAuth flow (GitHub) with state handling and token persistence.
- Build a lightweight data layer on SQLite using TypeScript.
- Expose the same business logic via HTTP routes, an SDK, a CLI, and an MCP server for AI agents.
Everything runs on Node.js LTS with Express, better-sqlite3, and TypeScript.
## Feature highlights
- (OAuth) `/auth/github/start` and `/auth/github/callback` wrap the GitHub dance.
- (Storage) Automatic SQLite table creation plus refresh scaffolding and repository helpers.
- (Services) Shared orchestration reused by HTTP routes, the CLI, the SDK, and MCP tools.
- (Tooling) Type-safe `IntegrationHubClient` SDK together with the `github-integration-hub` CLI.
- (Agents) MCP tools `github_start_auth`, `github_list_repos`, and `github_create_issue`.
## Getting started
### 1. Install dependencies
```bash
npm install
```
### 2. Configure environment
Copy `.env.example` to `.env` and set your GitHub OAuth credentials:
```
PORT=3000
DATABASE_FILE=./github-integration-hub.db
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_OAUTH_AUTHORIZE_URL=https://github.com/login/oauth/authorize
GITHUB_OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token
GITHUB_API_BASE_URL=https://api.github.com
GITHUB_REDIRECT_URI=http://localhost:3000/auth/github/callback
GITHUB_INTEGRATION_HUB_BASE_URL=http://localhost:3000
```
> Ensure the GitHub OAuth app redirect matches `GITHUB_REDIRECT_URI`.
### 3. Run the backend
Development mode with hot reload:
```bash
npm run dev
```
Production-style build + run:
```bash
npm run build
npm start
```
The server logs: `GitHub Integration Hub listening on port <port>`.
## MCP server (for AI agents)
Compile once, then launch the stdio server:
```bash
npm run build
npm run start:mcp
```
Tools available:
- `github_start_auth` – returns an authorization URL for a `userId`.
- `github_list_repos` – lists repos for the stored connection.
- `github_create_issue` – posts an issue using the saved token.
Point your MCP-aware IDE/CLI (for example Codex) to this stdio process and the tools become callable immediately.
## HTTP API reference
| Method | Path | Description |
|--------|------|-------------|
| POST | `/auth/github/start` | Returns `{ authUrl }` for `userId` |
| GET | `/auth/github/callback` | Exchanges `code` + `state`, saves tokens |
| GET | `/connections` | Lists connections (`?userId=` optional) |
| POST | `/actions/github/list-repos` | Lists repos via stored token |
| POST | `/actions/github/create-issue` | Creates an issue |
| GET | `/health` | Service heartbeat |
## CLI (`github-integration-hub`)
```bash
npm run build
npx github-integration-hub connections:list
npx github-integration-hub actions:list-repos --user alice
npx github-integration-hub actions:create-issue --user alice --owner my-org --repo api --title "Hello" --body "Proof from Cristian"
```
Flags:
- `--base-url` overrides `GITHUB_INTEGRATION_HUB_BASE_URL`.
- `connections:list --user <userId>` filters entries.
## SDK example
```ts
import { IntegrationHubClient } from 'github-integration-hub/sdk';
const client = new IntegrationHubClient({ baseUrl: process.env.GITHUB_INTEGRATION_HUB_BASE_URL! });
async function showcase() {
const { authUrl } = await client.startGithubAuth('user-123');
console.log('Send someone to authorize:', authUrl);
const repos = await client.listGithubRepos('user-123');
console.log(repos.map((repo) => repo.full_name));
}
```
## Manual OAuth test plan
1. `POST /auth/github/start` with `{ "userId": "demo-user" }`.
2. Visit the returned `authUrl`, approve the GitHub app.
3. Callback stores the connection automatically.
4. Trigger actions using HTTP, the CLI, SDK, or MCP tools.
## Project structure
```
.
|-- cli/ # CLI entry point
|-- sdk/ # TypeScript SDK
|-- src/
| |-- config/ # Environment helpers
| |-- db/ # SQLite init + repository
| |-- mcp/ # MCP server
| |-- providers/ # GitHub OAuth + API clients
| |-- routes/ # Express routers
| `-- services/ # Token manager + actions
|-- .env.example
|-- package.json
|-- tsconfig.json
`-- README.md
```
---
**Made by Cristian.** Ping me if you want to talk about backend integrations, OAuth design, or MCP tooling.