pub-mcp 0.1.0

package/.dockerignore

@@ -0,0 +1,13 @@
+node_modules/
+src/
+tests/
+.git/
+.gitignore
+*.md
+.env*
+!.env.example
+coverage/
+.DS_Store
+*.log
+dist/*.map
+dist/types/

package/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,js,json}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/.env.example

@@ -0,0 +1,15 @@
+# Cache Configuration
+CACHE_TTL=3600
+CACHE_MAX_ITEMS=500
+
+# Rate Limiting
+MAX_CONCURRENT_REQUESTS=5
+RETRY_ATTEMPTS=3
+
+# API Configuration
+PUB_DEV_API_URL=https://pub.dev/api
+GITHUB_API_URL=https://api.github.com
+GITHUB_TOKEN=
+
+# Logging
+LOG_LEVEL=info

package/.eslintrc.cjs

@@ -0,0 +1,21 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  plugins: ['@typescript-eslint'],
+  env: {
+    node: true,
+    es2022: true,
+  },
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-explicit-any': 'warn',
+  },
+};

package/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  release:
+    types: [published]
+
+jobs:
+  lint:
+    name: Lint
+    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
+
+  test:
+    name: 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 test
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'release'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog 📝
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2024-04-09
+
+### 🎉 Added
+
+- **Dual Transport Support** - Both stdio and Streamable HTTP
+  - `pub-mcp` - Both transports
+  - `pub-mcp --stdio` - Stdio only
+  - `pub-mcp --http` - HTTP only
+  - `pub-mcp --http --port 8080` - Custom port
+
+- **New MCP Tools**
+  - `get_package_score` - Get pana points, likes, downloads, tags
+  - `get_changelog` - Get package changelog
+  - `get_package_metrics` - Comprehensive metrics (info + score + versions)
+
+- **Enhanced `get_readme`**
+  - Added `format` parameter: `markdown`, `text`, `html`
+
+- **MCP Resources**
+  - `pub://popular-packages` - List of popular packages
+  - `pub://package/{name}` - Package documentation and metrics
+
+### 🛠️ Changed
+
+- Refactored CLI to unified entry point
+- Improved error handling in HTTP transport
+- Better structured logging
+
+### 📦 Dependencies
+
+- Updated `@modelcontextprotocol/sdk` to v1.29.0
+- Added `express` and `cors` for HTTP transport
+
+---
+
+## [0.0.1] - 2024-04-09
+
+### 🎉 Added
+
+- MCP server with stdio transport
+- pub.dev API client with search, getPackage, getPackageVersions, getReadme, getDependencies
+- LRU caching layer for package info, versions, readme, and search results
+- GitHub fallback integration for README when pub.dev has no content
+- Rate limiting with p-limit
+- CLI runner with health check and version commands
+- Structured logging with Pino
+- Unit tests for all modules
+- GitHub Actions CI workflow
+
+### 🛠️ Tools
+
+- `ping` - Check server health
+- `health` - Get server status
+- `search_packages` - Search packages on pub.dev
+- `get_package_info` - Get package details
+- `get_package_versions` - Get package versions
+- `get_readme` - Get package README (with GitHub fallback)
+- `get_dependencies` - Get package dependencies
+
+---
+
+## Roadmap 🗺️
+
+### Planned Features
+
+- [ ] SSE (Server-Sent Events) support for streaming
+- [ ] OAuth authentication for HTTP transport
+- [ ] Prometheus metrics endpoint
+- [ ] Health check endpoint with detailed status
+- [ ] Package search suggestions
+- [ ] Trending packages resource
+
+---
+
+<p align="right"><i>Changelog generated by <a href="https://github.com/conventional-changelog/conventional-changelog">conventional-changelog</a></i></p>

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Harassment of any kind
+- Publishing others' private information without permission
+- Disrespectful or discriminatory comments
+- Public or private harassment
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior.
+
+## Reporting
+
+Instances of abusive, harassing, or otherwise unacceptable behavior can be reported by contacting the maintainers.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant.

package/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to pub-mcp
+
+Thank you for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/pub-mcp.git`
+3. Install dependencies: `npm install`
+4. Create a feature branch: `git checkout -b feature/my-feature`
+
+## Development Workflow
+
+```bash
+# Run tests
+npm run test
+
+# Run linter
+npm run lint
+
+# Build
+npm run build
+
+# Run all checks
+npm run check
+```
+
+## Code Style
+
+- Use TypeScript
+- Follow existing code patterns
+- Run `npm run format` before committing
+- Ensure tests pass
+
+## Testing
+
+- Write tests for new features
+- Run `npm run test` to verify
+- Coverage target: 80%+
+
+##提交
+
+- Use clear commit messages
+- Reference issues in commits
+
+## Pull Requests
+
+1. Ensure all tests pass
+2. Ensure linting passes
+3. Update documentation if needed
+4. Submit PR with description
+
+## Questions?
+
+Open an issue for questions about contributing.

package/Dockerfile

@@ -0,0 +1,13 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY dist/ ./dist/
+
+ENV NODE_ENV=production
+
+ENTRYPOINT ["node", "dist/cli.js"]
+CMD ["start"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# pub-mcp 📦✨
+
+[![npm version](https://img.shields.io/npm/v/pub-mcp)](https://www.npmjs.com/package/pub-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/node/v/pub-mcp)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-3178c6?style=flat&logo=typescript)](https://www.typescriptlang.org)
+
+> MCP (Model Context Protocol) server for pub.dev - Open Source. Enables LLMs and AI assistants to access Dart/Flutter package information from pub.dev.
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Install globally
+npm install -g pub-mcp
+
+# Start server (stdio + HTTP)
+pub-mcp
+
+# Or start with just HTTP on custom port
+pub-mcp --http --port 8080
+```
+
+That's it! Your MCP server is running on port 3000 (HTTP) and listening on stdio.
+
+---
+
+## 🎯 Features
+
+| Feature                   | Description                                     |
+| ------------------------- | ----------------------------------------------- |
+| 🔍 **Package Search**     | Search packages on pub.dev by query             |
+| 📦 **Package Info**       | Get metadata, versions, publisher info          |
+| ⭐ **Package Score**      | Pana points, likes, downloads, tags             |
+| 📝 **Changelog**          | Package changelog for any version               |
+| 📊 **Metrics**            | Comprehensive metrics (info + score + versions) |
+| 📖 **README**             | Package README with GitHub fallback             |
+| 🔗 **Dependencies**       | Package dependency tree                         |
+| 🌐 **MCP Resources**      | Access packages as resources                    |
+| 🚇 **Dual Transport**     | Stdio and Streamable HTTP                       |
+| 💾 **LRU Caching**        | Built-in caching for performance                |
+| ⚡ **Rate Limiting**      | Retry with exponential backoff                  |
+| 📝 **Structured Logging** | Pino logger integration                         |
+
+---
+
+## 🚀 Usage
+
+### Starting the Server
+
+```bash
+# Both transports (default - stdio + HTTP on port 3000)
+pub-mcp
+
+# Stdio only (for Claude Desktop, etc.)
+pub-mcp --stdio
+
+# HTTP only
+pub-mcp --http
+
+# HTTP on custom port
+pub-mcp --http --port 8080
+
+# Check version
+pub-mcp --version
+
+# Check API health
+pub-mcp --health
+```
+
+### Connecting AI Clients
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pub-mcp": {
+      "command": "pub-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+#### Other MCP Clients
+
+```bash
+# Start HTTP server
+pub-mcp --http
+
+# Connect to http://localhost:3000/mcp
+```
+
+---
+
+## 🔧 Configuration
+
+Environment variables (optional, can be set in `.env`):
+
+| Variable                  | Default                  | Description                         |
+| ------------------------- | ------------------------ | ----------------------------------- |
+| `PORT`                    | `3000`                   | HTTP server port                    |
+| `CACHE_TTL`               | `3600`                   | Cache TTL in seconds                |
+| `CACHE_MAX_ITEMS`         | `500`                    | Maximum cache items                 |
+| `MAX_CONCURRENT_REQUESTS` | `5`                      | Concurrent request limit            |
+| `RETRY_ATTEMPTS`          | `3`                      | Retry attempts                      |
+| `PUB_DEV_API_URL`         | `https://pub.dev/api`    | pub.dev API URL                     |
+| `GITHUB_API_URL`          | `https://api.github.com` | GitHub API URL                      |
+| `GITHUB_TOKEN`            | -                        | GitHub token for higher rate limits |
+| `LOG_LEVEL`               | `info`                   | Logging level                       |
+
+---
+
+## 🛠️ MCP Tools
+
+| Tool                   | Description                   | Parameters                    |
+| ---------------------- | ----------------------------- | ----------------------------- |
+| `search_packages`      | 🔍 Search packages on pub.dev | `query`, `limit?`             |
+| `get_package_info`     | 📦 Get package details        | `name`                        |
+| `get_package_versions` | 📋 Get all package versions   | `name`                        |
+| `get_readme`           | 📖 Get package README         | `name`, `version?`, `format?` |
+| `get_dependencies`     | 🔗 Get package dependencies   | `name`, `version?`            |
+| `get_package_score`    | ⭐ Get score & metrics        | `name`                        |
+| `get_changelog`        | 📝 Get package changelog      | `name`, `version?`            |
+| `get_package_metrics`  | 📊 Get comprehensive metrics  | `name`                        |
+
+### 📖 Get Readme Format
+
+The `get_readme` tool supports a `format` parameter:
+
+```json
+{
+  "name": "get_readme",
+  "arguments": {
+    "name": "http",
+    "format": "markdown" // "markdown" | "text" | "html"
+  }
+}
+```
+
+---
+
+## 📚 MCP Resources
+
+| URI                      | Description                              |
+| ------------------------ | ---------------------------------------- |
+| `pub://popular-packages` | 📦 List of popular Dart/Flutter packages |
+| `pub://package/{name}`   | 📋 Package documentation and metrics     |
+
+---
+
+## 💡 Examples
+
+### 🔍 Search Packages
+
+```json
+{
+  "name": "search_packages",
+  "arguments": {
+    "query": "http client",
+    "limit": 5
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "packages": [
+    {
+      "name": "http",
+      "description": "A composable, Future-based library for making HTTP requests.",
+      "latestVersion": "1.2.1"
+    },
+    { "name": "dio", "description": "A powerful HTTP client for Dart.", "latestVersion": "5.4.0" }
+  ],
+  "total": 2
+}
+```
+
+### ⭐ Get Package Score
+
+```json
+{
+  "name": "get_package_score",
+  "arguments": {
+    "name": "http"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "grantedPoints": 160,
+  "maxPoints": 160,
+  "likeCount": 8425,
+  "downloadCount30Days": 8375591,
+  "tags": ["sdk:dart", "sdk:flutter", "topic:http", "topic:network"]
+}
+```
+
+### 📊 Get Package Metrics
+
+```json
+{
+  "name": "get_package_metrics",
+  "arguments": {
+    "name": "provider"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "info": {
+    "name": "provider",
+    "description": "A wrapper around InheritedNotifier...",
+    "latestVersion": "6.1.2",
+    "published": "2024-01-15T..."
+  },
+  "score": {
+    "grantedPoints": 160,
+    "maxPoints": 160,
+    "likeCount": 3200,
+    "downloadCount30Days": 1500000,
+    "tags": ["sdk:flutter", "is:flutter-friendly"]
+  },
+  "versionCount": 45,
+  "latestVersion": "6.1.2"
+}
+```
+
+---
+
+## 🏗️ Development
+
+```bash
+# Clone and install
+git clone https://github.com/yourusername/pub-mcp.git
+cd pub-mcp
+npm install
+
+# Build
+npm run build
+
+# Development mode with watch
+npm run dev
+
+# Run tests
+npm run test
+
+# Watch mode for tests
+npm run test:watch
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.
+
+---
+
+<p align="center">
+  Made with ❤️ for the Dart/Flutter community
+</p>

package/dist/cache/cache.d.ts

@@ -0,0 +1,27 @@
+export interface CacheOptions {
+    ttl: number;
+    maxItems: number;
+}
+export declare class LRUCache<T> {
+    private cache;
+    private ttl;
+    private maxItems;
+    constructor(options: CacheOptions);
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl?: number): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    clear(): void;
+    size(): number;
+    private cleanup;
+    stats(): {
+        size: number;
+        hits: number;
+        misses: number;
+    };
+}
+export declare function createCache<T>(options: CacheOptions): LRUCache<T>;
+export declare function getPackageCache(): LRUCache<unknown>;
+export declare function getSearchCache(): LRUCache<unknown>;
+export declare function clearAllCaches(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache/cache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,YAAY;IAMjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAkB/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAY9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,MAAM;IAKd,OAAO,CAAC,OAAO;IASf,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAOxD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEjE;AAUD,wBAAgB,eAAe,IAAI,QAAQ,CAAC,OAAO,CAAC,CAKnD;AAED,wBAAgB,cAAc,IAAI,QAAQ,CAAC,OAAO,CAAC,CAKlD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}