# AI Service Integration Starter

A reusable Next.js starter for exposing product capabilities to ChatGPT, Claude,
and other MCP clients. It includes a stateless Streamable HTTP MCP endpoint,
OAuth discovery, strict resource/audience binding, optional social sign-in, and
defensive structured-output helpers.

The repository intentionally contains no product data model, company domain,
credentials, or deployment configuration. It is a safe starting point, not a
ready-to-publish OAuth provider.

## What is included

| Area | Included | You must provide |
|---|---|---|
| MCP | Stateless Streamable HTTP route and one example read-only tool | Product tools and authorization rules |
| OAuth resource server | Discovery challenge and JWT issuer/audience verification | Production signing keys and authorization server |
| OAuth authorization server | Metadata builder plus explicit unimplemented route seams | Metadata route, consent UI, DCR, code exchange, refresh rotation, persistent store |
| Social sign-in | Google, Kakao, and Naver providers appear only when configured | Provider credentials and account-linking policy |
| Structured AI output | Provider-neutral adapter and defensive JSON extraction | A provider adapter, schema validation, retries, and quota policy |
| Verification | Unit tests, lint, typecheck, build, and CI | Real-client and restart tests after integration |

OAuth authorization-server metadata and issuance routes deliberately return
`501` until the application supplies a durable implementation. This prevents a
demo-only in-memory flow from being advertised as a deployable security boundary.

## Quick start

```bash
corepack enable
pnpm install
cp .env.example .env.local
pnpm dev
```

Useful endpoints:

- `GET /health`
- `POST /mcp`
- `GET /.well-known/oauth-protected-resource`
- `GET /.well-known/oauth-authorization-server`
- `GET|POST /api/auth/*` when at least one social provider is configured

Run the local checks:

```bash
pnpm typecheck
pnpm lint
pnpm test --run
pnpm build
```

## Apply this starter with an agent

Give the agent the repository plus the product specification, then require it to
work through these gates in order. Do not ask it to copy another product's OAuth
tables or tools verbatim.

1. **Define the boundary.** Name the product capability, users, MCP tools,
   read/write effects, data policy, public origins, and deployment target.
2. **Replace placeholders.** Update `APP_NAME`, `PUBLIC_APP_ORIGIN`,
   `OAUTH_ISSUER`, `MCP_RESOURCE`, `PROTECTED_RESOURCE_METADATA_URL`, allowed
   browser origins, scopes, tool names, schemas, and copy.
   Origins must come from configuration, never an incoming `Host` header.
3. **Implement identity and consent.** Decide how a signed-in user approves an
   MCP client. Keep social sign-in separate from OAuth delegation and never merge
   accounts using email or display name alone.
4. **Implement durable OAuth state.** Add DCR, one-time authorization codes,
   refresh-token families, hashing, rotation, reuse detection, and migrations in
   a store that survives restarts. Only short-lived authorization codes may be
   process-local, and production should normally persist those too.
5. **Preserve resource binding.** Carry the exact canonical `resource` through
   authorize, code, token, refresh, JWT `aud`, and MCP verification. Reject
   missing or mismatched values at every boundary.
6. **Add product tools.** Replace `example_lookup`; annotate every tool accurately
   (`readOnlyHint`, `destructiveHint`, `openWorldHint`) and validate both input
   and output at runtime.
7. **Add the model adapter only if needed.** Use a structured-output API supported
   by the chosen model, then validate the parsed value against the product schema.
   Retry only transient failures and do not log API keys or credential-bearing URLs.
8. **Prove the whole flow.** Test discovery → DCR → PKCE S256 → consent → code
   exchange → MCP call → refresh rotation, then restart the service and repeat
   with the existing client and refresh token. Add negative tests for wrong and
   missing resources, redirect URI mismatch, code replay, and refresh reuse.

Suggested task prompt:

```text
Adapt this starter for <product>. Read README.md and AGENTS.md first.
Keep all public origins explicit in environment variables. Implement the OAuth
store with migrations and restart-safe tests. Preserve resource binding from the
authorize request through the access-token aud claim and MCP verification.
Replace the example MCP tool with <tools>, including accurate annotations and
runtime input/output validation. Do not copy product-specific names, data, URLs,
or credentials from another repository. Run typecheck, lint, unit tests, build,
and the documented end-to-end OAuth flow before reporting completion.
```

An agent is not finished when the code compiles. It is finished when the real
client flow and restart behavior pass against the intended deployment topology.

## Architecture

```text
MCP client
  -> POST /mcp
  <- 401 + WWW-Authenticate(resource_metadata=...)
  -> protected-resource metadata
  -> authorization-server metadata
  -> authorization code + PKCE S256 + user consent
  -> access token whose aud equals MCP_RESOURCE
  -> POST /mcp with Bearer token
```

See [docs/architecture.md](docs/architecture.md) for invariants and
[docs/oauth-store.sql](docs/oauth-store.sql) for a portable persistence model.

## Environment

Copy `.env.example` to `.env.local`. Public origins and the MCP resource are
separate settings even when they currently share a host. Do not infer any of them
from request headers.

`OAUTH_SIGNING_SECRET` is a development convenience for HS256 verification. Use
asymmetric keys, rotation, and a published JWKS in a real multi-service system.

## Public-release checklist

Keep the GitHub repository private until all items are complete:

- Confirm the MIT license and `SPACEWALK` copyright are still intended.
- Search the full tracked tree and Git history for organization names, private
  hosts, credentials, customer data, internal package registries, and proprietary
  copied code.
- Replace placeholder privacy, terms, support, icon, and documentation URLs.
- Enable secret scanning and push protection.
- Review dependency licenses and run a vulnerability scan.
- Verify the repository from a clean clone with no untracked local files.
- Treat making the repository public as a separate human-approved action.

## License

MIT © 2026 SPACEWALK. See [LICENSE](LICENSE).