# Aether MCP Server

**Warning: This project has not completed a security review and is not suitable for production use. See [SECURITY_REVIEW.md](SECURITY_REVIEW.md) for known issues.**

A Model Context Protocol (MCP) server providing system utilities, file operations, data tools, a creative idea generator, prompts, and dynamic resources with bearer-token and OAuth 2.0 authentication.

## Features

### System Tools
- **system_info** — Detailed OS, CPU, memory, and disk information (basic or full report)

### File Tools
- **read_file** — Read files with optional line-range support
- **write_file** — Create or overwrite files
- **list_files** — List directory contents with file sizes and timestamps (recursive + filter support)

### Utility Tools
- **generate_uuid** — Generate UUIDs (v4) in string, brackets, or URN format
- **generate_password** — Generate secure passwords with customizable character sets
- **base64_handler** — Encode/decode strings to/from base64
- **json_handler** — Pretty-print, minify, list keys, or validate JSON
- **timestamp_converter** — Convert between Unix timestamps and ISO dates; generate current timestamps

### Creative Idea Tools
- **generate_idea** — Generate unique business/product/startup ideas by combining random concepts, techniques, and domains
- **generate_name** — Generate brandable names for products, startups, or projects
- **combine_concepts** — Fuse arbitrary concepts, techniques, and domains into creative combinations

### MCP Prompts
- **business_plan** — Generate a structured business plan outline
- **code_review** — Return a comprehensive code review checklist
- **market_analysis** — Generate a market analysis framework
- **product_requirements** — Generate a PRD outline
- **tech_stack_advisor** — Recommend a complete technical stack
- **debug_assistant** — A systematic debugging workflow

### MCP Resources
- **system://hostname** — System hostname
- **system://uptime** — System uptime, load averages, memory/CPU summary
- **system://env** — Environment variables (sensitive values redacted)
- **system://cpus** — Detailed CPU architecture information
- **process://info** — Current Node.js process information
- **file:///{path}** — Read files within the workspace root (dynamic template resource)

## Authentication

### Bearer Token (API Key)
Set `AETHER_API_KEY` to enable simple bearer token authentication for HTTP mode:

```bash
AETHER_API_KEY=my-secret AETHER_TRANSPORT=http node dist/index.js
```

Clients send `Authorization: Bearer my-secret` with requests.

### OAuth 2.0
Set `AETHER_OAUTH_CLIENT_SECRETS` to enable OAuth 2.0 with a self-hosted token endpoint:

```bash
AETHER_TRANSPORT=http AETHER_OAUTH_CLIENT_SECRETS='{"my-client":"my-secret"}' \
  AETHER_PUBLIC_URL=http://127.0.0.1:3000/mcp node dist/index.js
```

**Endpoints** (auto-served when OAuth is enabled):
- `GET /.well-known/oauth-authorization-server` — RFC 8414 authorization server metadata
- `GET /.well-known/oauth-protected-resource/mcp` — RFC 9728 protected resource metadata
- `GET /.well-known/jwks.json` — JWKS (RS256 signing keys)
- `POST /oauth/token` — Token endpoint (client_credentials, authorization_code, refresh_token)
- `POST /oauth/revoke` — Token and refresh token revocation
- `POST /oauth/introspect` — Token introspection
- `POST /oauth/register` — Dynamic client registration
- `GET /health` — Health check endpoint

**Token endpoint** (client credentials):
```bash
curl -X POST http://127.0.0.1:3000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=my-client&client_secret=my-secret&scope=mcp"
```

Returns a JWT access token plus a refresh token:
```json
{
  "access_token": "...",
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "expires_in": 3600,
  "scope": "mcp",
  "refresh_token": "..."
}
```

**Refresh token** (rotate access tokens without re-authenticating):
```bash
curl -X POST http://127.0.0.1:3000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=...&client_id=my-client"
```

**Authorization code flow with PKCE**:
```bash
# 1. Get authorization code
open "http://127.0.0.1:3000/oauth/authorize?response_type=code&client_id=my-client&redirect_uri=http://127.0.0.1:3000/callback&code_challenge=abc123&code_challenge_method=S256"

# 2. Exchange code for token
curl -X POST http://127.0.0.1:3000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=...&code_verifier=abc123&client_id=my-client&redirect_uri=http://127.0.0.1:3000/callback"
```

Use the token in the `Authorization: Bearer <token>` header for MCP requests.

## Transports

### stdio (local)
Default mode. Connects as a subprocess — used by Claude Desktop, Claude Code, Cursor, etc.

### HTTP (remote)
Set `AETHER_TRANSPORT=http` to enable Streamable HTTP transport.

```bash
AETHER_TRANSPORT=http AETHER_PORT=3000 node dist/index.js
AETHER_TRANSPORT=http AETHER_ENABLE_SESSIONS=true node dist/index.js  # stateful
```

Register with `http://localhost:3000/mcp` in MCP clients that support HTTP/SSE transport.

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AETHER_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `AETHER_PORT` | `3000` | HTTP server port |
| `AETHER_HOST` | `127.0.0.1` | HTTP server host |
| `AETHER_API_KEY` | — | Bearer token for API key auth mode |
| `AETHER_OAUTH_CLIENT_SECRETS` | — | JSON map of `client_id: client_secret` for OAuth |
| `AETHER_PUBLIC_URL` | `http://host:port/mcp` | Public URL for OAuth discovery |
| `AETHER_RATE_LIMIT` | `100` | Max requests per minute per client IP |
| `AETHER_MAX_BODY_SIZE` | `1048576` | Max request body size in KB (default 1MB) |
| `AETHER_CORS_ORIGINS` | `http://localhost:3000,http://127.0.0.1:3000` | Allowed CORS origins |
| `AETHER_PKCE_REQUIRED` | `true` | Require PKCE for authorization code flow |
| `AETHER_ENABLE_SESSIONS` | `false` | Enable stateful sessions |

## Security

This project is a work in progress and has not completed a security audit. Known issues are documented in [SECURITY_REVIEW.md](SECURITY_REVIEW.md). Do not expose this server to the public internet or use it with sensitive data until the issues identified in that review have been addressed.

## Prerequisites

- Node.js 20+

## Installation & Usage

### Local Development

```bash
npm install

npm run dev            # stdio mode
npm run dev:http       # HTTP mode
npm run build          # compile TypeScript
npm start              # stdio mode (built)
npm run start:http     # HTTP mode (built)
```

### Connect to an MCP Client

**Claude Desktop / Claude Code** (stdio mode):
```json
{ "mcpServers": { "aether": { "command": "node", "args": ["/PATH/TO/aether-mcp/dist/index.js"] } } }
```

**Claude Code HTTP mode**:
```bash
claude mcp add aether --transport http http://localhost:3000/mcp
```

### Testing

**Unit tests** (vitest + InMemoryTransport):
```bash
npm test          # watch mode
npm run test:run  # single run
```

**MCP Inspector**:
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Open http://localhost:6274 to interact with all tools, resources, and prompts in a web UI.

## Project Structure

```
aether-mcp/
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── README.md
├── SECURITY_REVIEW.md
├── .gitignore
└── src/
    ├── index.ts            # Entry point: transport selection (stdio or HTTP), HTTP server with auth
    ├── server.ts           # Server factory — registers all tools, resources, and prompts
    ├── resources.ts        # MCP resource registrations (system, process, file template)
    ├── auth.ts             # Auth: JWT tokens, refresh tokens, bearer auth gate
    ├── oauth.ts            # OAuth 2.0: discovery, token/revoke/introspect/register endpoints, PKCE
    ├── rateLimit.ts        # Rate limiter: in-memory store with per-IP tracking
    ├── prompts.ts          # 6 MCP prompts
    ├── tools/
    │   ├── system.ts       # System info tool
    │   ├── files.ts        # File read/write/list tools
    │   ├── utils.ts        # Data utility tools
    │   └── ideas.ts        # Creative idea generation tools
    └── test/
        ├── tools.test.ts     # 22 tests for all 12 tools
        ├── resources.test.ts # 13 tests for resources and templates
        ├── prompts.test.ts   # 8 tests for all 6 prompts
        └── auth.test.ts      # 4 tests for token store and auth config
```

## License

MIT