# self-mcp-server

FastMCP server for querying FRED financial and macroeconomic data plus AKShare A-share stock basics.

Design doc:

- [FRED FastMCP Server 设计文档](docs/fred_fastmcp_design.md)
- [MCP Server 部署目录说明](docs/mcp_deployments.md)

## Setup

```powershell
uv sync
$env:FRED_API_KEY = ""
uv run python main.py
```

Alternatively, create a local `.env` file from `.env.example`:

```powershell
Copy-Item .env.example .env
```

Then set `FRED_API_KEY` in `.env`. The server loads it from environment variables via `python-dotenv`; the key is never exposed as a tool parameter.

## Local MCP Loader Demo

This repo also includes a small local MCP loader demo. The config is in
`deployments/mcp.local.yaml` and follows the same simple stdio shape used by
Codex/OpenCode-style MCP configs: server name plus `command`, `args`, `env`,
and optional `env_files`.

The demo loads:

- `fred`: this local FRED MCP server via `.venv/Scripts/python.exe main.py`
- `github`: the local Docker image `docker.xuanyuan.run/mcp/github:latest`

Prepare local secrets:

```powershell
Copy-Item .env.example .env
Copy-Item deployments/github-mcp/.env.example deployments/github-mcp/.env
```

Set `FRED_API_KEY` in `.env` and `GITHUB_PERSONAL_ACCESS_TOKEN` in
`deployments/github-mcp/.env`.

Run the demo:

```powershell
.venv\Scripts\python.exe scripts\demo_load_mcp_servers.py
```

It initializes both MCP servers, lists their tools, and calls one sample tool on
each server.

For HTTP mode, these can also live in `.env`:

```text
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765
MCP_PATH=/mcp
MCP_STATELESS_HTTP=true
MCP_JSON_RESPONSE=true
```

HTTP mode for curl-based E2E checks:

```powershell
$env:MCP_TRANSPORT = "http"
$env:MCP_HOST = "127.0.0.1"
$env:MCP_PORT = "8765"
$env:MCP_PATH = "/mcp"
uv run python main.py
```

## Tools

- `fred_search_series`
- `fred_get_series`
- `fred_get_observations`
- `fred_get_latest_observation`
- `fred_get_vintage_dates`
- `fred_get_canonical_indicators`
- `fred_get_macro_snapshot`
- `akshare_stock_zh_a_code_name`
- `akshare_stock_profile_cninfo`
- `akshare_stock_valuation_em`
- `akshare_stock_financial_abstract`
- `akshare_stock_basic_metrics`

All tools return a common envelope:

```json
{
  "ok": true,
  "data": {},
  "meta": {
    "source": "FRED",
    "endpoint": "series/observations",
    "cached": false,
    "fetched_at": "2026-05-13T12:00:00Z"
  },
  "request": {},
  "warnings": []
}
```