# Gooseworks MCP

An Express server that exposes tools through the Model Context Protocol (MCP) Streamable HTTP transport, including a set of GitHub tools.

The MCP endpoint is:

```text
http://localhost:4000/mcp
```

Every request must include the bearer token configured by `MCP_AUTH_TOKEN`.

## Requirements

- Node.js `v25.2.1`
- pnpm `11.5.3`
- Docker Engine and Docker Compose v2 for container deployment
- A GitHub personal access token with the permissions required by the tools you plan to use

## Configuration

The server loads variables from a local `.env` file or the process environment:

| Variable         | Required | Default | Description                                  |
| ---------------- | -------- | ------- | -------------------------------------------- |
| `PORT`           | No       | `4000`  | Port on which the HTTP server listens        |
| `GITHUB_TOKEN`   | Yes      | None    | GitHub personal access token used by Octokit |
| `MCP_AUTH_TOKEN` | Yes      | None    | Bearer token required for every MCP request  |

Create a local environment file from the template:

```bash
cp .env.template .env
```

Edit `.env` and replace both placeholder token values. Use a long, randomly generated value for `MCP_AUTH_TOKEN`, and grant the GitHub token only the permissions needed by this server. Never commit `.env` or paste either token into a public issue, log, or image.

## Run Locally

1. Install dependencies:

   ```bash
   pnpm install
   ```

2. Create and configure `.env` as described above.

3. Start the server:

   ```bash
   pnpm start
   ```

   This runs the same entrypoint as `pnpm exec tsx src/index.ts`.

For development with automatic restart after source changes, use:

```bash
pnpm dev
```

To check the TypeScript project without emitting files:

```bash
pnpm typecheck
```

The server is ready when the console reports that it is active on `http://localhost:<PORT>/mcp`. Configure your MCP client to use that URL and send:

```http
Authorization: Bearer <MCP_AUTH_TOKEN>
```

## Deploy With Docker Compose

1. Install Docker Engine with Docker Compose v2 on the host.

2. Clone this repository and enter its directory:

   ```bash
   git clone <repository-url>
   cd gooseworks-mcp
   ```

3. Create the deployment environment file:

   ```bash
   cp .env.template .env
   ```

4. Set `GITHUB_TOKEN` and a strong, private `MCP_AUTH_TOKEN` in `.env`. Set `PORT` if the service should listen on a different host/container port. The same value is used for both sides of the Compose port mapping.

5. Build and start the service in the background:

   ```bash
   docker compose up --build -d
   ```

6. Follow the service logs or stop it when needed:

   ```bash
   docker compose logs -f gooseworks-mcp
   docker compose down
   ```

The Compose configuration passes the three supported variables into the container and fails early if either required token is missing. For a public deployment, place the service behind an HTTPS reverse proxy and keep port `4000` or your chosen `PORT` private when possible. MCP clients should use the proxy's HTTPS `/mcp` URL and the configured bearer token.

## Available Tools

The server registers the following tools:

#### GitHub

- Reading the authenticated profile
- Listing repositories, branches, and commits
- Searching code
- Reading file contents
- Creating issues
- Creating pull requests

## License

This project is licensed under the [MIT License](LICENSE.md). It is free to use, fork, modify, and redistribute for any purpose, subject to the license terms.