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

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 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)

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

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.