MCP Server Sample

A sample repository demonstrating two ways to run an MCP (Model Context Protocol) server using Python or TypeScript: stdio (local subprocess) and HTTP (Python uses HTTP/SSE, TypeScript uses Streamable HTTP).

What It Does

Both servers expose a calculate_powers tool that computes the square, cube, and 4th power of a number. The HTTP server also adds a calculate_negative_powers tool, a numberpowers://info resource containing historical notes about number powers, and a powers_explanation prompt.

Project Structure

├── .gitignore
├── LICENSE
├── README.md
├── stdiomcpconfig_opencode.json    # opencode config for Python stdio server
├── py/                             # Python implementation
│   ├── server.py                   # Stdio MCP server (single tool)
│   ├── server_http.py              # HTTP/SSE MCP server (two tools + resource + prompt)
│   ├── requirements.txt            # Python dependencies
│   ├── numberPowers.txt            # Text file served as a resource
│   └── opencode.json               # opencode config for Python HTTP server
└── ts/                             # TypeScript implementation
    ├── server.ts                   # Stdio MCP server (single tool)
    ├── server_http.ts              # Streamable HTTP MCP server (two tools + resource + prompt)
    ├── package.json                # Node.js dependencies
    ├── tsconfig.json               # TypeScript configuration
    ├── numberPowers.txt            # Text file served as a resource
    └── opencode.json               # opencode config for TypeScript HTTP server

Prerequisites

• Python 3.10+ (for Python implementation)
• Node.js 18+ (for TypeScript implementation)
• An MCP-compatible client (e.g., opencode)

Setup

Python

cd py
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

TypeScript

cd ts
npm install
npm run build

Running the Servers

Python - Stdio Server (py/server.py)

The stdio server runs as a subprocess and communicates over stdin/stdout. It exposes one tool: calculate_powers.

cd py
python server.py

Python - HTTP/SSE Server (py/server_http.py)

The HTTP server runs on http://localhost:8000 and communicates over Server-Sent Events (SSE). It exposes two tools (calculate_powers, calculate_negative_powers), one resource (numberpowers://info), and one prompt (powers_explanation).

cd py
python server_http.py

The SSE endpoint is available at http://localhost:8000/sse.

TypeScript - Stdio Server (ts/server.ts)

cd ts
npm run start

TypeScript - HTTP Server (ts/server_http.ts)

The TypeScript HTTP server runs on http://localhost:8001 and uses the Streamable HTTP transport. It exposes two tools (calculate_powers, calculate_negative_powers), one resource (numberpowers://info), and one prompt (powers_explanation).

cd ts
npm run start:http

The MCP endpoint is available at http://localhost:8001/mcp.

Adding to opencode

Option 1: Stdio (local subprocess)

Python

The repository includes stdiomcpconfig_opencode.json at the project root with this configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "number-powers": {
      "type": "local",
      "command": ["python", "py/server.py"],
      "enabled": true
    }
  }
}

TypeScript

Add the following to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "number-powers": {
      "type": "local",
      "command": ["node", "ts/dist/server.js"],
      "enabled": true
    }
  }
}

Adjust the command array to use absolute paths if needed.

Option 2: HTTP (remote server)

Start the HTTP server first, then add this to your opencode.json:

Python

The repository includes py/opencode.json with this configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "number-powers-http": {
      "type": "remote",
      "url": "http://localhost:8000/sse",
      "enabled": true
    }
  }
}

TypeScript

The repository includes ts/opencode.json with this configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "number-powers-http": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "enabled": true
    }
  }
}

Applying Changes

After saving opencode.json, restart opencode for the MCP server to be available.

Available MCP Capabilities

Server	Type	Tools	Resources	Prompts
py/server.py	stdio	calculate_powers(number)	—	—
py/server_http.py	HTTP/SSE (port 8000)	calculate_powers(number), calculate_negative_powers(number)	numberpowers://info	powers_explanation(number)
ts/server.ts	stdio	calculate_powers(number)	—	—
ts/server_http.ts	Streamable HTTP (port 8001)	calculate_powers(number), calculate_negative_powers(number)	numberpowers://info	powers_explanation(number)

Tool Details

calculate_powers — Accepts a number, returns its square, cube, and 4th power as a comma-separated string.

calculate_negative_powers — Accepts a number, returns its negative powers (n^-1, n^-2, n^-3) as a comma-separated string. (HTTP server only)

numberpowers://info — Returns historical notes about number powers from ancient civilizations. (HTTP server only)

Prompt Details

powers_explanation — Accepts a number and returns a prompt asking the LLM to calculate and explain all powers of that number (square, cube, 4th power, and negative powers). (HTTP server only)

Invoking Prompts in OpenCode

OpenCode supports invoking MCP prompts through the chat interface. To use the powers_explanation prompt:

1. Start the HTTP server: python server_http.py or npm run start:http
2. In OpenCode, mention the prompt in your message, for example:

   Use the powers_explanation prompt for number 22
   

3. OpenCode will call the MCP server's prompts/get endpoint with the prompt name and arguments.

Alternatively, you can manually invoke the prompt via the MCP protocol:

{
  "method": "prompts/get",
  "params": {
    "name": "powers_explanation",
    "arguments": {
      "number": 22
    }
  }
}

License

See LICENSE.