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/startand/auth/github/callbackwrap 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
IntegrationHubClientSDK together with thegithub-integration-hubCLI. - (Agents) MCP tools
github_start_auth,github_list_repos, andgithub_create_issue.
Getting started
1. Install dependencies
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:
npm run dev
Production-style build + run:
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:
npm run build
npm run start:mcp
Tools available:
github_start_auth– returns an authorization URL for auserId.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)
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-urloverridesGITHUB_INTEGRATION_HUB_BASE_URL.connections:list --user <userId>filters entries.
SDK example
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
POST /auth/github/startwith{ "userId": "demo-user" }.- Visit the returned
authUrl, approve the GitHub app. - Callback stores the connection automatically.
- 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.