# 6DuckLearn MCP

Official public setup docs, registry metadata, and local connector package for 6DuckLearn integrations.

This repository contains two separate integrations: Hosted MCP lets Codex use 6DuckLearn tools; the AI Runtime Connector lets Agent Console send work to Codex, Hermes, or OpenClaw.

Use `6ducklearn` as the local client key in Codex or Claude Code. The official MCP Registry name is `com.6ducklearn/mcp`, and the hosted endpoint is:

```text
https://6ducklearn.com/mcp
```

This repository is intentionally hosted-first. It does not contain the private 6DuckLearn SaaS backend, Supabase edge functions, service-role database access, billing logic, user memory store, or production deployment scripts.

## Quick Start

### Codex

From GitHub:

```bash
npx github:kit18/6ducklearn-mcp setup-codex
```

This configures the hosted 6DuckLearn MCP server in local Codex, adds the hosted OAuth compatibility header, and starts the OAuth login flow.
If a matching, authenticated `6ducklearn` hosted entry already exists, the setup command keeps it in place and does not reopen OAuth. A different local or stdio entry is replaced, while a matching but signed-out entry resumes OAuth, so repeated setup stays deterministic without creating duplicates.

Manual fallback:

Do not use `codex mcp add` for this fallback: current Codex versions can start OAuth immediately from that command, before explicit scopes are supplied. Inspect the entry first with `codex mcp get 6ducklearn --json`:

- If it is missing, add the full block below to `~/.codex/config.toml`.
- If it already uses the URL below, keep its server table and add only the missing `http_headers` table.
- If it uses another URL or transport, run `codex mcp remove 6ducklearn`, then add the full block.

```toml
[mcp_servers.6ducklearn]
url = "https://6ducklearn.com/mcp"

[mcp_servers.6ducklearn.http_headers]
User-Agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125 Safari/537.36"
```

Start only the explicitly scoped login:

```bash
codex mcp login 6ducklearn --scopes mcp:read,mcp:write
```

### Claude Code

```bash
claude mcp add --transport http 6ducklearn https://6ducklearn.com/mcp
```

Then open the MCP tool picker in Claude Code and authorize 6DuckLearn when prompted.

### npm Package Status

The npm packages `@6ducklearn/mcp` and `@6ducklearn/connector` are not published yet. Until npm publication is available, use the GitHub `npx` command above for copy/paste setup.

## Hosted MCP Identity

- local client key: `6ducklearn`
- MCP Registry name: `com.6ducklearn/mcp`
- title: `6DuckLearn MCP`
- MCP URL: `https://6ducklearn.com/mcp`
- OAuth discovery: `https://6ducklearn.com/.well-known/oauth-authorization-server`
- protected resource metadata: `https://6ducklearn.com/.well-known/oauth-protected-resource/mcp`

The public Codex helper requests only `mcp:read` and `mcp:write`. Control-plane access and local-runtime authorization use separate, explicitly named flows; the public hosted-MCP setup never requests `approval:decide`. Write-capable and sensitive actions remain controlled by 6DuckLearn runtime policy and user approval.

## What Agents Can Do

6DuckLearn MCP gives connected agents account-authorized workflows for research, organization, reminders, portfolio review, knowledge retrieval, canvas creation, and Skill Builder discovery. Finance research includes bounded stock-research bundles and issuer-grounded Hong Kong credit-card evaluation when those capabilities are enabled for the connected account.

For the full public catalog, see [MCP tool use cases](./docs/tool-use-cases.md). The catalog describes each tool by practical use case and example prompt without exposing private schemas or backend implementation details.

Finance-related capabilities are for research, organization, summaries, alerts, and user-authorized workflows. 6DuckLearn MCP is not an order-routing service or source of investment recommendations.

### Finance Research Examples

Ask for a stock bundle when you want the available value, timing, event, risk, saved-research, and portfolio inputs in one read-only response:

```text
Build a 90-day cached research bundle for 0700.HK. Include upcoming dates for the next 90 days, identify stale or missing evidence, and do not give trading instructions.
```

For Hong Kong credit cards, separate evidence lookup from evaluation:

```text
First show the published dining-card evidence and freshness. Then evaluate annual net value for HKD 8,000 of monthly dining spend, excluding welcome offers and disclosing every missing or unverified field.
```

`query_credit_card_catalog` never ranks cards. `recommend_credit_cards` evaluates only the currently published, source-linked catalog and may return a limited, stale, or insufficient-data status instead of a winner. Missing normalized fields remain disclosures; they are not permission to invent reward rates, eligibility, fees, or ranking evidence.

## Advanced: AI Runtime Connector

The connector is for users who want a local runtime bridge between 6DuckLearn and AI runtimes such as Codex, OpenClaw, or Hermes. The preferred setup path is OAuth from the 6DuckLearn web app.

```bash
npm install
npm run build
SIXDUCK_PUBLIC_BASE_URL=https://6ducklearn.com node packages/connector/dist/index.js login
```

After login, keep the connector process running when using a local runtime:

```bash
SIXDUCK_RUNTIME_TYPE=codex \
SIXDUCK_CODEX_CWD=/absolute/path/to/your/workspace \
SIXDUCK_CODEX_QUIET_PROFILE=true \
node packages/connector/dist/index.js
```

Most users should start from the hosted 6DuckLearn setup page rather than cloning this repository directly.

## MCP Registry Publication

The official registry manifest lives in [`server.json`](./server.json). It is a hosted-only listing because the canonical 6DuckLearn MCP server runs at `https://6ducklearn.com/mcp`; the local connector is a runtime bridge, not a standalone stdio MCP server package.

Before publishing, validate the manifest and hosted endpoint:

```bash
npm run validate:registry
npm run smoke:hosted
```

Publish with domain-based authentication so the registry name can stay under the 6DuckLearn domain namespace:

```bash
# After generating the proof key and serving /.well-known/mcp-registry-auth:
mcp-publisher login http --domain 6ducklearn.com --algorithm ecdsap384 --private-key "$PRIVATE_KEY"
mcp-publisher publish
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=com.6ducklearn/mcp"
```

The required HTTP proof must be served from `https://6ducklearn.com/.well-known/mcp-registry-auth`. After the official MCP Registry lists `com.6ducklearn/mcp`, request GitHub MCP Registry inclusion by emailing `partnerships@github.com` with the registry name, official registry URL, GitHub repository, website, hosted endpoint, and validation evidence. GitHub's MCP Registry is a separate curated surface, so listing there currently requires GitHub review rather than relying on automatic community registry sync.

## What Is Public Here

- hosted MCP setup instructions
- official MCP Registry manifest
- sanitized client examples
- local connector source and tests
- live hosted endpoint smoke checks
- secret scans that prevent private SaaS details from entering this public repo

## What Stays Private

- 6DuckLearn SaaS application source
- production Supabase functions and migrations
- service-role database patterns
- user memory, PKM, billing, approval trails, and runtime health data
- internal release scripts and production deploy credentials

## Development

```bash
npm install
npm run validate
```

Validation runs TypeScript build, connector tests, package dry-run, MCP Registry manifest checks, hosted MCP smoke checks, and a public-release secret scan.

## Security

Report security issues privately. See [SECURITY.md](./SECURITY.md).

## License

Code is licensed under Apache-2.0. Documentation examples are licensed under CC BY 4.0. See [TRADEMARK.md](./TRADEMARK.md) for 6DuckLearn brand usage.