feat: implement MCP server with 7 tools for project discovery

.claude/rules/conventions.md

@@ -0,0 +1,17 @@
+# Conventions
+
+## Code Style
+- TypeScript strict mode
+- ESM modules (import/export, `.js` extensions in imports)
+- Vitest for tests
+- Zod for schema validation
+
+## Testing
+- Tests in `tests/` mirroring `src/` structure
+- Use vitest `describe`/`it` blocks
+- Mock the OSTClient in tool tests, mock `fetch` in client tests
+- One assertion focus per test
+
+## Git
+- Conventional commits: `feat:`, `fix:`, `test:`, `chore:`, `docs:`
+- Follow TDD: write failing test first, then implement

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build

.gitignore

@@ -137,3 +137,9 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Local notes
+TODO.local.md
+
+# Worktrees
+.worktrees/

CLAUDE.md

@@ -0,0 +1,78 @@
+# 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 Linker REST API 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 Linker API
+```
+
+- `src/index.ts` — MCP server entry point, registers all tools
+- `src/client.ts` — HTTP client for the OST Linker REST API
+- `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_URL` | OST Linker API base URL | `https://api.opensource-together.com` |
+
+## 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_URL": "https://api.opensource-together.com"
+      }
+    }
+  }
+}
+```

README.md

@@ -1,2 +1,53 @@
-# ost-mcp
-Official OST's MCP. Need a project ? Ask your agent to find it.
+# @opensource-together/mcp
+
+> Need a project? Just ask your agent.
+
+Stop browsing GitHub. Tell your AI agent what you need — it finds the right open-source project for you. Works with Claude, OpenClaw, and any MCP-compatible agent.
+
+## Quick Start
+
+Add this to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "ost": {
+      "command": "npx",
+      "args": ["@opensource-together/mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `search_projects` | Search by keyword + filter by category, domain, or tech stack |
+| `get_project` | Get full details on any project |
+| `get_trending` | See what's hot right now |
+| `find_similar` | Find similar projects using AI embeddings |
+| `list_categories` | Browse all categories |
+| `list_domains` | Browse all domains |
+| `list_techstacks` | Browse all tech stacks |
+
+## How it works
+
+Ask your agent > [@ost-mcp](https://github.com/opensource-together/ost-mcp) > [@ost-linker](https://github.com/opensource-together/ost-linker) > projects found
+
+- *"Find me React projects for e-commerce"*
+- *"What's trending in open source right now?"*
+- *"Show me projects similar to FastAPI"*
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run dev
+```
+
+## License
+
+MIT