From cdb87edde65eec7d05edc7a0928417f9c33b0e19 Mon Sep 17 00:00:00 2001 From: spideystreet Date: Wed, 29 Apr 2026 19:14:27 +0200 Subject: [PATCH] docs: add AGENTS.md and point CLAUDE/GEMINI at it Single agent guide for commands, gateway URL, env, tools, npm snippet. --- AGENTS.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 83 +------------------------------------------------------ GEMINI.md | 1 + 3 files changed, 82 insertions(+), 82 deletions(-) create mode 100644 AGENTS.md create mode 100644 GEMINI.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f0e2886 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,80 @@ +# ost-mcp + +Agent-facing guide for **[ost-mcp](https://github.com/opensource-together/ost-mcp)** — the [`@opensource-together/mcp`](https://www.npmjs.com/package/@opensource-together/mcp) MCP server used from Claude Desktop, IDEs, and other MCP clients. + +User-facing README: [README.md](README.md). + +## Project overview + +- **Upstream HTTP API:** Requests go to **`OST_API_URL`** (default: **`https://api.opensource-together.com/v1/mcp`**), the platform **MCP gateway** served by **[ost-backend](https://github.com/opensource-together/ost-backend)** (`Authorization: Bearer` + `OST_API_KEY`). +- **Data / recommendations:** Recommendations ultimately come from the **[ost-linker](https://github.com/opensource-together/ost-linker)** pipeline; this npm package talks only to the gateway base URL above. + +Flow: MCP client → stdio server (`src/index.ts`) → `OSTClient` (`src/client.ts`) → HTTP gateway. + +## Repository layout + +| Path | Role | +|------|------| +| `src/index.ts` | MCP server entry: registers tools | +| `src/client.ts` | HTTP client (paths under the gateway base URL) | +| `src/config.ts` | **`OST_API_URL`**, **`OST_API_KEY`** (required) | +| `src/types.ts` | Shared response types | +| `src/tools/*.ts` | One module per MCP tool | + +## Commands + +Run from **`ost-mcp/`** (this repo): + +```bash +npm install +npm run build # compile TypeScript → dist/ +npm run dev # tsc --watch +npm start # node dist/index.js +npm test # unit tests (Vitest) +npm run test:integration # hits a live API — set OST_API_URL / OST_API_KEY +npm run lint # tsc --noEmit +``` + +## MCP tools (current) + +| Tool | Role | +|------|------| +| `search_projects` | Keyword search + optional category, domain, tech stack | +| `get_project` | Full project by id | +| `get_trending` | Trending / popular projects | +| `find_similar` | Similar projects (embeddings) | +| `list_categories` | Reference: categories | +| `list_domains` | Reference: domains | +| `list_techstacks` | Reference: tech stacks | + +## Configuration + +| Variable | Required | Purpose | +|---------|----------|---------| +| `OST_API_KEY` | **Yes** | Personal access token; sent as `Authorization: Bearer`. | +| `OST_API_URL` | No | Gateway base URL (no trailing slash). Default: `https://api.opensource-together.com/v1/mcp`. | + +For local development against another host, set both variables in the MCP client’s `env` block. + +## npm / MCP client snippet + +```json +{ + "mcpServers": { + "ost": { + "command": "npx", + "args": ["@opensource-together/mcp"], + "env": { + "OST_API_KEY": "", + "OST_API_URL": "https://api.opensource-together.com/v1/mcp" + } + } + } +} +``` + +Generate tokens in OpenSource Together account settings. + +## License + +See **MIT** in [package.json](./package.json) / [README.md](./README.md). diff --git a/CLAUDE.md b/CLAUDE.md index 539b8d9..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,82 +1 @@ -# CLAUDE.md - -## Project Overview - -OST MCP is the Model Context Protocol server for [OpenSourceTogether](https://opensource-together.com/). It lets developers discover and explore open-source projects directly from Claude Desktop, IDEs, and other MCP-compatible clients. - -It consumes the OST backend MCP gateway and exposes 7 MCP tools for project search, discovery, and similarity. - -## Common Commands - -### Development -```bash -npm install # Install dependencies -npm run build # Compile TypeScript -npm run dev # Watch mode -npm test # Run tests (vitest) -npm run lint # Type check (tsc --noEmit) -``` - -### Testing -```bash -npx vitest run # All tests -npx vitest run tests/tools/ # Tool tests only -npx vitest --watch # Watch mode -``` - -## Architecture - -``` -User (Claude Desktop/IDE) -> MCP Server (stdio) -> OSTClient (HTTP) -> OST backend MCP gateway -``` - -- `src/index.ts` — MCP server entry point, registers all tools -- `src/client.ts` — HTTP client for the OST backend MCP gateway -- `src/tools/` — One file per MCP tool (or group) -- `src/config.ts` — Reads `OST_API_URL` from env -- `src/types.ts` — Shared TypeScript types - -## MCP Tools (v1) - -| Tool | Description | -|------|-------------| -| `search_projects` | Search projects by keyword with optional filters | -| `get_project` | Get full project details by ID | -| `get_trending` | Get trending/popular projects | -| `find_similar` | Find similar projects via AI embeddings | -| `list_categories` | List all categories | -| `list_domains` | List all domains | -| `list_techstacks` | List all tech stacks | - -## Environment Variables - -| Variable | Purpose | Default | -|----------|---------|---------| -| `OST_API_KEY` | Personal Access Token from your OST account | **required** | -| `OST_API_URL` | OST backend MCP gateway base URL | `https://api.opensource-together.com/v1/mcp` | - -## Related Repos - -- [ost-linker](https://github.com/opensource-together/ost-linker) — AI recommendation pipeline + REST API that this MCP consumes -- [ost-backend](https://github.com/opensource-together/ost-backend) — Main OST platform backend - -## Distribution - -Published as `@opensource-together/mcp` on npm. Users install via: - -```json -{ - "mcpServers": { - "ost": { - "command": "npx", - "args": ["@opensource-together/mcp"], - "env": { - "OST_API_KEY": "your-personal-access-token", - "OST_API_URL": "https://api.opensource-together.com/v1/mcp" - } - } - } -} -``` - -> Generate your key at your OpenSource Together account settings. +@AGENTS.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md