ibge-br-mcp 1.9.0

package/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Run tests with coverage
+        if: matrix.node-version == '20.x'
+        run: npm run test:coverage
+
+      - name: Upload coverage reports
+        if: matrix.node-version == '20.x'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+        continue-on-error: true
+
+  type-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+  security:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit
+        run: npm audit --audit-level=high
+        continue-on-error: true

package/.github/workflows/publish.yml

@@ -0,0 +1,118 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Dry run (do not publish)"
+        required: false
+        default: "false"
+        type: boolean
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify package contents
+        run: npm pack --dry-run
+
+      - name: Check package version
+        id: version
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          echo "version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
+          echo "Package version: $PACKAGE_VERSION"
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'false')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create publish summary
+        run: |
+          echo "## 📦 Package Published" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Package:** ibge-br-mcp" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** $(node -p "require('./package.json').version")" >> $GITHUB_STEP_SUMMARY
+          echo "**Registry:** https://www.npmjs.com/package/ibge-br-mcp" >> $GITHUB_STEP_SUMMARY
+
+  dry-run:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Dry run publish
+        run: |
+          echo "## 🧪 Dry Run - Package would be published" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Package:** ibge-br-mcp" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** $(node -p "require('./package.json').version")" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Package Contents:" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          npm pack --dry-run 2>&1 >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

package/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+All notable changes to the IBGE MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.9.0] - 2024
+
+### Added
+- **Países tool** (`ibge_paises`): Query international country data from IBGE
+  - List all countries (UN M49 methodology)
+  - Search countries by name
+  - Filter by region/continent (Americas, Europe, Africa, Asia, Oceania)
+  - Get detailed country information (area, languages, currency, indicators)
+- **Cidades tool** (`ibge_cidades`): Query municipal indicators (similar to Cidades@IBGE portal)
+  - Municipal panorama with key indicators (population, GDP, HDI, etc.)
+  - Historical indicator data over time
+  - Research and indicator listing
+- **Test suite**: Comprehensive unit tests for paises and cidades tools (36 new tests)
+- **Package metadata**: Added homepage and bugs.url fields
+
+### Changed
+- All 23 tool descriptions standardized to English for MCP catalog compatibility
+- README completely rewritten in English with comprehensive documentation
+
+### Fixed
+- Phase 4 tools (ibge_paises, ibge_cidades) now properly registered in main server
+- SERVER_VERSION updated to 1.9.0
+- Fixed 14 ESLint non-null assertion warnings using nullish coalescing
+
+## [1.8.0] - 2024
+
+### Added
+- **LICENSE**: MIT license file
+- **.npmignore**: Proper npm package exclusions
+
+### Fixed
+- All linter warnings resolved (0 warnings)
+
+## [1.7.0] - 2024
+
+### Added
+- **Testing framework**: Vitest with comprehensive test suite
+  - 173 unit tests covering validation, cache, errors, retry, and formatters
+  - Test coverage configuration (v8 provider)
+  - Test timeout settings for network operations
+
+## [1.6.0] - 2024
+
+### Added
+- **Retry mechanism**: Exponential backoff for network failures
+  - Configurable retry count and delay
+  - Custom retry conditions
+  - Retry utility for fetch operations
+
+## [1.5.0] - 2024
+
+### Added
+- **Centralized validation**: Input validation with descriptive error messages
+  - IBGE code validation (regions, states, municipalities, districts)
+  - UF normalization (abbreviation to code conversion)
+  - Date format validation
+  - Period validation (years, ranges, quarters)
+  - Territorial level validation
+  - CNAE code validation
+
+### Changed
+- All tools now use centralized validation
+
+## [1.4.0] - 2024
+
+### Added
+- **Centralized error handling**: Consistent error messages across all tools
+  - HTTP error parsing with helpful suggestions
+  - Validation error formatting
+  - Tool-specific error context
+
+### Changed
+- All tools now use centralized error handling
+
+## [1.3.0] - 2024
+
+### Added
+- **ESLint + Prettier**: Code quality and formatting
+  - TypeScript-aware linting rules
+  - Consistent code formatting
+  - Pre-configured for ES modules
+
+## [1.2.0] - 2024
+
+### Added
+- **Performance metrics**: Request tracking and performance monitoring
+  - Request duration tracking
+  - API endpoint categorization
+  - Success/failure statistics
+  - Average response times
+
+### Changed
+- All tools now report metrics via `withMetrics` wrapper
+
+## [1.1.0] - 2024
+
+### Added
+- **Centralized utilities**: Common formatting functions
+  - `formatNumber`: Locale-aware number formatting
+  - `truncate`: String truncation with ellipsis
+  - `createMarkdownTable`: Markdown table generation
+  - `buildQueryString`: URL query string construction
+
+### Changed
+- All tools migrated to use centralized utilities
+- Consistent number and date formatting across all tools
+
+## [1.0.0] - 2024
+
+### Added
+- **Cache system**: In-memory caching with TTL
+  - Configurable TTL levels (STATIC, MEDIUM, SHORT, REALTIME)
+  - Cache key generation with parameter normalization
+  - Automatic cache expiration
+
+### Changed
+- All tools now use caching for improved performance
+
+## [0.9.0] - 2024
+
+### Added
+- **Phase 3 tools**:
+  - `ibge_malhas_tematicas`: Thematic meshes (health regions, metropolitan areas)
+  - `bcb_inflacao`: Central Bank inflation data (IPCA, IGP-M, INPC)
+  - `datasaude`: Health indicators (mortality, life expectancy, sanitation)
+  - `ibge_indicadores`: Economic and social indicators (GDP, unemployment, IPCA)
+
+## [0.8.0] - 2024
+
+### Added
+- **Phase 2 tools**:
+  - `ibge_noticias`: IBGE news and releases
+  - `ibge_calendario`: IBGE release calendar
+  - `ibge_sidra_metadados`: SIDRA table metadata
+  - `ibge_pesquisas`: IBGE research surveys
+  - `ibge_sidra_tabelas`: SIDRA table search
+  - `ibge_censo`: Census data (2022 and 2010)
+  - `ibge_cnae`: CNAE economic activity codes
+
+## [0.7.0] - 2024
+
+### Added
+- **Phase 1 tools**:
+  - `ibge_estados`: Brazilian states
+  - `ibge_municipios`: Municipalities by state
+  - `ibge_distritos`: Districts
+  - `ibge_localidades`: Localities search
+  - `ibge_regioes`: Geographic regions
+  - `ibge_sidra`: SIDRA data queries
+  - `ibge_nomes`: Name frequency statistics
+  - `ibge_ranking_nomes`: Name rankings
+  - `ibge_malhas`: Geographic meshes (GeoJSON/TopoJSON)
+
+## [0.1.0] - 2024
+
+### Added
+- Initial MCP server setup
+- Basic project structure
+- TypeScript configuration
+- Package configuration
+
+---
+
+For more details on each release, see the [commit history](https://github.com/SidneyBissoli/ibge-br-mcp/commits/main).

package/CONTRIBUTING.md

@@ -0,0 +1,285 @@
+# 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](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Adding New Tools](#adding-new-tools)
+- [Testing](#testing)
+- [Code Style](#code-style)
+- [Submitting Changes](#submitting-changes)
+
+## 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
+
+```bash
+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:
+
+```typescript
+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`:
+
+```typescript
+export * from "./my-tool.js";
+```
+
+### Step 3: Register in Main Server
+
+Register the tool in `src/index.ts`:
+
+```typescript
+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`:
+
+```typescript
+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
+
+```bash
+# 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:
+
+```bash
+# 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!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sidney Bissoli
+
+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.