Aether MCP Server

Warning: This project has not completed a security review and is not suitable for production use. See 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:

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:

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

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:

{
  "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):

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:

# 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.

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

Security

This project is a work in progress and has not completed a security audit. Known issues are documented in 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

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

{ "mcpServers": { "aether": { "command": "node", "args": ["/PATH/TO/aether-mcp/dist/index.js"] } } }

Claude Code HTTP mode:

claude mcp add aether --transport http http://localhost:3000/mcp

Testing

Unit tests (vitest + InMemoryTransport):

npm test          # watch mode
npm run test:run  # single run

MCP Inspector:

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