# erickwendel-contributions-mcp

![CI Status](https://github.com/ErickWendel/erickwendel-contributions-mcp/workflows/Test%20MCP%20Server/badge.svg)
[![npm version](https://badge.fury.io/js/@erickwendel%2Fcontributions-mcp.svg)](https://www.npmjs.com/package/@erickwendel/contributions-mcp)
[![npm downloads](https://img.shields.io/npm/dt/@erickwendel/contributions-mcp.svg)](https://www.npmjs.com/package/@erickwendel/contributions-mcp)

A Model Context Protocol (MCP) server that exposes tools to query [Erick Wendel's contributions](https://erickwendel.com.br/) across talks, blog posts, and videos. Use this server with MCP-aware clients such as Claude Desktop, Cursor, or any compatible MCP runtime.

## Overview

- **Tools:** `get-talks`, `get-posts`, `get-videos`, `check-status`
- **Prompts:** `find-content`, `summarize-activity`
- **Resources:** `erickwendel://about`, `erickwendel://statistics`
- **Built with:** Node.js, TypeScript, MCP SDK, Zod
- **Requires:** Node.js `>=20.0.0`

## Features

- Query talks, posts, and videos using structured MCP tool calls
- Support filtering by ID, title, language, city, country, year, and portal
- Provide metadata and resource endpoints for server discovery
- Enable prompt-driven queries for content search and high-level summaries
- Run locally or consume directly from npm using `npx`

## Install & Run Locally

```bash
git clone https://github.com/erickwendel/erickwendel-contributions-mcp.git
cd erickwendel-contributions-mcp
npm ci
npm start
```

> `npm start` runs the server on STDIO using `node --experimental-strip-types --no-warnings src/index.ts`.

## Available Scripts

- `npm start` — Run the MCP server locally
- `npm run dev` — Run the server with `--inspect` and file watching
- `npm run inspect` — Inspect the MCP capabilities with the MCP Inspector
- `npm test` — Run unit tests
- `npm run lint` — Lint source and test files
- `npm run lint:fix` — Fix lint issues where possible

## Using the Published Package

Use this package directly without cloning the repository:

```json
{
  "mcpServers": {
    "erickwendel-contributions": {
      "command": "npx",
      "args": ["-y", "@erickwendel/contributions-mcp"]
    }
  }
}
```

## MCP Server Capabilities

### Tools

- `get-talks`
  - Filters: `id`, `title`, `language`, `city`, `country`, `year`
  - Supports pagination and grouped counts by language/country/city
- `get-posts`
  - Filters: `id`, `title`, `language`, `portal`
  - Supports pagination
- `get-videos`
  - Filters: `id`, `title`, `language`
  - Supports pagination
- `check-status`
  - Confirms the server is alive and responding

### Prompts

- `find-content`
  - Build a query for talks, posts, or videos using topic and language filters
- `summarize-activity`
  - Generate a summary of content activity, optionally filtered by year

### Resources

- `erickwendel://about` — Information about Erick Wendel and server metadata
- `erickwendel://statistics` — Content statistics and recommended queries

## MCP Client Integration

### Cursor

Add or update `~/.cursor/mcp.json` with:

```json
{
  "mcpServers": {
    "erickwendel-contributions": {
      "command": "npx",
      "args": ["-y", "@erickwendel/contributions-mcp"]
    }
  }
}
```

For local development, point Cursor to the local project entry file:

```json
{
  "mcpServers": {
    "erickwendel-contributions": {
      "command": "node",
      "args": ["--experimental-strip-types", "/absolute/path/to/project/src/index.ts"]
    }
  }
}
```

### Claude Desktop

Add the same MCP server definition to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS:

```json
{
  "mcpServers": {
    "erickwendel-contributions": {
      "command": "npx",
      "args": ["-y", "@erickwendel/contributions-mcp"]
    }
  }
}
```

For local development, use the local project path instead of `npx`.

### MCPHost with Ollama

If you prefer a free MCP runtime, use [MCPHost](https://github.com/mark3labs/mcphost) together with Ollama:

```bash
go install github.com/mark3labs/mcphost@latest
```

Create a config file, for example `./mcp.jsonc`:

```json
{
  "mcpServers": {
    "erickwendel-contributions": {
      "command": "npx",
      "args": ["-y", "@erickwendel/contributions-mcp"]
    }
  }
}
```

Then run:

```bash
ollama pull MODEL_NAME
mcphost --config ./mcp.jsonc -m ollama:MODEL_NAME
```

## Example Queries

Use your MCP client to ask questions such as:

- "How many talks were given in 2023?"
- "Show me talks in Spanish"
- "Find posts about WebXR"
- "List videos in Portuguese"

## Development Notes

- Entry point: `src/index.ts`
- MCP server configuration: `src/config/api.ts`
- Tools implementation: `src/tools/talks.ts`, `src/tools/posts.ts`, `src/tools/videos.ts`, `src/tools/status.ts`
- GraphQL and type helpers: `erickwendel-sdk/`

## Requirements

- Node.js `>=20.0.0`
- npm

## License

MIT


- Built with Model Context Protocol (MCP)
- **Full MCP Capabilities**: Tools, Prompts, and Resources
- Type-safe with TypeScript and Zod schema validation
- Native TypeScript support in Node.js without transpilation
- Generated SDK using [GenQL](https://genql.dev)
- Modular architecture with separation of concerns
- Standard I/O transport for easy integration
- Structured error handling
- Compatible with Claude Desktop, Cursor, and [MCPHost](https://github.com/mark3labs/mcphost) (free alternative)

> Note: This project requires Node.js v23+ as it uses the native TypeScript support added in the last year.

## Architecture

The codebase follows a modular structure:

```
src/
  ├── config/      # Configuration settings
  ├── types/       # TypeScript interfaces and types
  ├── tools/       # MCP tool implementations
  ├── utils/       # Utility functions
  ├── services/    # API service layer
  └── index.ts     # Main entry point
```

## Testing

To run the test suite:

```bash
npm test
```

For development mode with watch:

```bash
npm run test:dev
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

* Repository code: [Erick Wendel](https://github.com/ErickWendel/erickwendel-contributions-mcp)

## Author

[Erick Wendel](https://linktr.ee/erickwendel)

## License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.