Content
# MCP Server Collection
> Five **production-grade** [Model Context Protocol](https://modelcontextprotocol.io)
> servers — TypeScript **and** Python — with typed tool schemas (Zod / Pydantic),
> stdio + HTTP transports, **mock-by-default backends** (so they run with zero
> credentials), tests, and an npm / PyPI publish pipeline.
<!-- Badges placeholder: test · publish-npm · publish-pypi · license -->
---
## Contents
- [The servers](#the-servers)
- [Why it's production-grade](#why-its-production-grade)
- [Prerequisites](#prerequisites)
- [Installation & running](#installation--running)
- [Use in Claude Desktop](#use-in-claude-desktop)
- [Use in an agent framework](#use-in-an-agent-framework)
- [Transports & auth](#transports--auth)
- [Connecting a real backend](#connecting-a-real-backend)
- [Testing](#testing)
- [Publishing](#publishing)
- [Repository layout](#repository-layout)
- [Troubleshooting](#troubleshooting)
## The servers
| Package | Lang | Module / build | Tools |
|---------|------|----------------|-------|
| [`postgres-pgvector`](packages/postgres-pgvector) | Py | `pgvector_mcp.server` | `semantic_search` `sql_query` `vector_upsert` |
| [`bedrock-tools`](packages/bedrock-tools) | Py | `bedrock_mcp.server` | `invoke_claude` `invoke_llama` `knowledge_base_retrieve` `agent_invoke` |
| [`foundry-tools`](packages/foundry-tools) | Py | `foundry_mcp.server` | `foundry_chat` `foundry_search` `foundry_agent_run` |
| [`confluence-jira`](packages/confluence-jira) | TS | `@mcpc/confluence-jira` | `search_pages` `read_page` `create_page` `search_issues` `create_issue` `transition_issue` |
| [`hotel-crm`](packages/hotel-crm) | TS | `@mcpc/hotel-crm` | `search_reservations` `get_guest_profile` `list_loyalty_rewards` |
Every server **runs with zero credentials** out of the box (mock backend) — try,
test, and demo before wiring anything real.
## Why it's production-grade
- **Typed tool schemas** — Zod (TS) / Pydantic (Py); no untyped inputs.
- **Two transports** — `stdio` (Claude Desktop, local agents) and **HTTP**
(Streamable HTTP / SSE), with a bearer-token check for remote use.
- **Backend-behind-an-interface** — mock by default, real backend by config.
- **Tested** — unit tests against the mock backend; MCP Inspector–validatable.
- **Composable** — `examples/` wires servers into LangGraph and Semantic Kernel.
- **Publishable** — npm (provenance) + PyPI (Trusted Publishing).
Full design + conventions: [docs/architecture.md](docs/architecture.md) ·
[adding a server](docs/adding-a-server.md) · [deployment](docs/deployment.md).
## Prerequisites
- **Python 3.12+** for the Python servers.
- **Node 20+** and **pnpm 11+** (`npm install -g pnpm`) for the TypeScript servers.
## Installation & running
### Python servers
```bash
cd packages/postgres-pgvector
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python -m pgvector_mcp.server # speaks MCP over stdio (mock backend)
```
The same pattern works for `bedrock-tools` (`bedrock_mcp.server`) and
`foundry-tools` (`foundry_mcp.server`).
### TypeScript servers
```bash
pnpm install # from the repo root
pnpm --filter @mcpc/confluence-jira build
node packages/confluence-jira/dist/server.js # stdio (mock backend)
```
## Use in Claude Desktop
Add servers to `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
```json
{
"mcpServers": {
"pgvector": { "command": "python", "args": ["-m", "pgvector_mcp.server"] },
"confluence-jira": {
"command": "node",
"args": ["/abs/path/packages/confluence-jira/dist/server.js"]
}
}
}
```
Full combined config: [examples/claude-desktop-config](examples/claude-desktop-config).
## Use in an agent framework
- **LangGraph** (via `langchain-mcp-adapters`): [examples/langgraph-integration](examples/langgraph-integration)
- **Semantic Kernel** (via `MCPStdioPlugin`): [examples/semantic-kernel](examples/semantic-kernel)
Both compose multiple servers into one agent against the mock backends.
## Transports & auth
- **stdio** (default) — trust is the launching process; no network auth.
- **HTTP** — Python: `MCP_TRANSPORT=http python -m <pkg>.server` (Streamable
HTTP / SSE). The TS servers ship a bearer-token check (`src/auth.ts`) for the
HTTP path. Always front HTTP with TLS + a bearer/OAuth2 token in production.
Validate any server with the MCP Inspector:
`npx @modelcontextprotocol/inspector python -m pgvector_mcp.server`.
## Connecting a real backend
Each server's tool logic calls a `Backend` interface whose default is the mock.
Implement the interface against the real service and select it by config:
| Server | Extra | Real backend |
|--------|-------|--------------|
| postgres-pgvector | `[postgres]` | asyncpg + pgvector |
| bedrock-tools | `[aws]` | boto3 (bedrock-runtime / agent-runtime) |
| foundry-tools | `[azure]` | Azure OpenAI + Azure AI Search |
| confluence-jira | — | Atlassian REST (token + base URL) |
## Testing
```bash
# Python (per package)
pytest packages/postgres-pgvector --cov --cov-report=term-missing
# TypeScript (all workspace packages)
pnpm -r build && pnpm -r test
```
Python servers are at 100% coverage; TS servers build clean with `tsc` and pass
vitest. CI runs both (`.github/workflows/test.yml`).
## Publishing
- **npm** (TS): push a `ts-v*` tag → `publish-npm.yml` builds, tests, publishes
with provenance (`NPM_TOKEN` secret).
- **PyPI** (Py): push a `py-v*` tag → `publish-pypi.yml` builds each package and
publishes via Trusted Publishing (OIDC, no stored token).
## Repository layout
```
packages/
├── postgres-pgvector/ # Python (FastMCP)
├── bedrock-tools/ # Python
├── foundry-tools/ # Python
├── confluence-jira/ # TypeScript (@modelcontextprotocol/sdk)
└── hotel-crm/ # TypeScript
examples/ # Claude Desktop, LangGraph, Semantic Kernel
docs/ # architecture, adding-a-server, deployment
pnpm-workspace.yaml # TS workspace
```
## Troubleshooting
- **`pnpm install` errors about ignored build scripts (esbuild)** — already
handled via `onlyBuiltDependencies` in `pnpm-workspace.yaml`; if you hit it on
a fresh clone, run `pnpm install` again or `pnpm rebuild esbuild`.
- **Python server "module not found"** — install that package first
(`pip install -e ".[dev]"` inside its directory).
## License
MIT (see [LICENSE](LICENSE)).
