Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
285 lines (216 loc) · 6.86 KB

CONTRIBUTING.md

File metadata and controls

285 lines (216 loc) · 6.86 KB

Contributing to IBGE MCP Server

Thank you for your interest in contributing to the IBGE MCP Server! This document provides guidelines and information for contributors.

Table of Contents

Code of Conduct

Please be respectful and constructive in all interactions. We welcome contributors of all experience levels.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR-USERNAME/ibge-br-mcp.git
  3. Create a feature branch: git checkout -b feature/your-feature-name
  4. Make your changes
  5. Submit a pull request

Development Setup

Prerequisites

  • Node.js 18.0.0 or higher
  • npm

Installation

cd ibge-br-mcp
npm install

Available Scripts

Command Description
npm run build Compile TypeScript to JavaScript
npm run watch Watch mode for development
npm run dev Build and run the server
npm run lint Run ESLint
npm run lint:fix Run ESLint with auto-fix
npm run format Format code with Prettier
npm run format:check Check formatting
npm test Run tests
npm run test:watch Run tests in watch mode
npm run test:coverage Run tests with coverage report
npm run inspector Open MCP Inspector

Project Structure

ibge-br-mcp/
├── src/
│   ├── index.ts          # Main MCP server and tool registration
│   ├── types.ts          # TypeScript type definitions
│   ├── cache.ts          # In-memory caching system
│   ├── metrics.ts        # Performance metrics tracking
│   ├── errors.ts         # Error handling utilities
│   ├── validation.ts     # Input validation functions
│   ├── retry.ts          # Retry mechanism for network calls
│   ├── config.ts         # Configuration and constants
│   ├── tools/            # Individual tool implementations
│   │   ├── estados.ts
│   │   ├── municipios.ts
│   │   ├── sidra.ts
│   │   └── ...
│   └── utils/            # Utility functions
│       ├── formatters.ts
│       └── index.ts
├── tests/                # Test files
│   ├── validation.test.ts
│   ├── cache.test.ts
│   └── ...
├── dist/                 # Compiled JavaScript (generated)
└── package.json

Adding New Tools

Step 1: Create the Tool File

Create a new file in src/tools/ with the following structure:

import { z } from "zod";
import { IBGE_API } from "../types.js";
import { cacheKey, CACHE_TTL, cachedFetch } from "../cache.js";
import { withMetrics } from "../metrics.js";
import { createMarkdownTable } from "../utils/index.js";
import { parseHttpError, ValidationErrors } from "../errors.js";

// Define the input schema using Zod
export const myToolSchema = z.object({
  param1: z.string().describe("Description of param1"),
  param2: z.number().optional().default(10).describe("Description of param2"),
});

export type MyToolInput = z.infer<typeof myToolSchema>;

// Implement the tool function
export async function myTool(input: MyToolInput): Promise<string> {
  return withMetrics("my_tool", "api_category", async () => {
    try {
      // Your implementation here
      const url = `${IBGE_API.LOCALIDADES}/...`;
      const key = cacheKey(url);
      const data = await cachedFetch<YourType>(url, key, CACHE_TTL.MEDIUM);

      // Format and return results
      return formatResults(data);
    } catch (error) {
      if (error instanceof Error) {
        return parseHttpError(error, "my_tool", { param1: input.param1 });
      }
      return ValidationErrors.emptyResult("my_tool");
    }
  });
}

// Export tool definition
export const myToolTool = {
  name: "my_tool",
  description: `Description of your tool in English.

Features:
- Feature 1
- Feature 2

Examples:
- Example usage 1
- Example usage 2`,
  inputSchema: myToolSchema,
  handler: myTool,
};

Step 2: Export from Tools Index

Add your export to src/tools/index.ts:

export * from "./my-tool.js";

Step 3: Register in Main Server

Register the tool in src/index.ts:

import { myToolSchema, myTool } from "./tools/my-tool.js";

// In the tools section:
server.tool(
  "my_tool",
  `Tool description in English...`,
  myToolSchema.shape,
  async (args) => {
    const result = await myTool(args);
    return { content: [{ type: "text", text: result }] };
  }
);

Step 4: Add Tests

Create a test file tests/my-tool.test.ts:

import { describe, it, expect } from "vitest";
import { myToolSchema } from "../src/tools/my-tool.js";

describe("myToolSchema", () => {
  it("should accept valid input", () => {
    const result = myToolSchema.safeParse({ param1: "value" });
    expect(result.success).toBe(true);
  });

  // Add more tests...
});

Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

  • Place test files in the tests/ directory
  • Name test files with .test.ts suffix
  • Use descriptive test names
  • Test both valid and invalid inputs
  • Mock external API calls for integration tests

Code Style

ESLint & Prettier

The project uses ESLint and Prettier for code quality:

# Check for linting issues
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

Style Guidelines

  • Use TypeScript for all code
  • Use ES modules (.js extension in imports)
  • Prefer const over let
  • Use descriptive variable and function names
  • Add JSDoc comments for public functions
  • Keep functions focused and small
  • Use centralized utilities instead of inline implementations

Tool Description Guidelines

  • Write tool descriptions in English
  • Include a brief summary
  • List key features
  • Provide usage examples
  • Be concise but informative

Submitting Changes

Pull Request Process

  1. Ensure all tests pass: npm test
  2. Ensure no linting errors: npm run lint
  3. Update documentation if needed
  4. Add entries to CHANGELOG.md
  5. Create a pull request with a clear description

Commit Messages

Use clear, descriptive commit messages:

Add new tool for X functionality

- Implement X feature
- Add tests for X
- Update documentation

Review Process

  • All changes require review before merging
  • Address review feedback promptly
  • Keep discussions constructive

Questions?

If you have questions, please:

  1. Check existing issues
  2. Read the documentation
  3. Open a new issue with your question

Thank you for contributing!