mcp server

harish-sewasetu-ai

SewaSetu AI - Autonomous Agentic Public Welfare & Pension Portal by Harish featuring dual MCP servers, RFC 9728 discovery, OAuth 2.1 privilege segregation, and live persona evaluation framework.

12636373/harish-sewasetu-aicommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 28, 2026

🏛️ SewaSetu AI

Autonomous Agentic Public Welfare & Pension Infrastructure

📑 Table of Contents

Overview
System Architecture
Key Innovations & Technical Pillars
Interactive Endpoints Directory
MCP Toolsets Reference
Quick Start & Local Setup
Connecting Agent Clients (Claude Code, Cursor, Windsurf)
Test Suites & Quality Verification
Directory Structure
Security & Prompt Injection Defenses
Author & License

💡 Overview

Public distribution systems and state welfare pensions often present severe hurdles for the vulnerable and elderly: opaque application queues, complex documentation requirements, and inflexible bureaucratic portals.

SewaSetu AI solves this by establishing an agent-ready civic bridge:

Citizens interact seamlessly with an AI Assistant powered by specialized Model Context Protocol (MCP) tools that check eligibility, lodge verified pension claims, track progress, generate certified receipts, and submit grievances.
Administrative Officers supervise the scheme with high-assurance tools to review backlogs, inspect uploaded credentials, approve or reject applications with auditable notes, and manage block queues.
Strict Privilege Segregation: Citizen agents are physically prevented from ever viewing or invoking officer-scoped administrative tools. Authorization boundaries are enforced at the protocol and cryptographic layers via OAuth 2.1 and RS256 token verification.

🏗️ System Architecture

flowchart TD
    subgraph Citizens["Citizen & Public Domain"]
        C1["Senior Citizen / Applicant"]
        C2["Citizen AI Agent (Claude / Assistant)"]
        C3["Web Browser (Senior Accessibility UI)"]
    end

    subgraph Officers["Administrative Domain"]
        O1["Block Welfare Officer"]
        O2["Administrative AI Agent"]
        O3["Departmental Admin Portal"]
    end

    subgraph Gateway["Edge & Security Layer (Caddy / Reverse Proxy)"]
        D1["RFC 8414 Authorization Discovery<br>/.well-known/oauth-authorization-server"]
        D2["RFC 9728 Protected Resource Metadata<br>/.well-known/oauth-protected-resource"]
        JWKS["JWKS Public Key Set<br>/.well-known/jwks.json"]
    end

    subgraph MCPServers["Model Context Protocol Core"]
        MCP_C["Citizen MCP Server<br>(/mcp/citizen)<br>Scope: citizen | 10 Tools"]
        MCP_O["Officer MCP Server<br>(/mcp/officer)<br>Scope: officer | 10 Tools"]
    end

    subgraph CoreBackend["Application & Persistence"]
        APP["Flask Web Application Core<br>(State Machine, PDF Engine, OTP Engine)"]
        DB[("PostgreSQL 15 Database<br>(100k Seed Records, Audit Ledger)")]
        SCHED["RTPS Nightly Scheduler<br>(Statutory 15-Day Deemed Approval)"]
        SMS["Simulated SMS Gateway<br>(/__gateway/)"]
    end

    C1 --> C3
    C2 -->|Streamable HTTP / SSE| MCP_C
    C3 --> APP

    O1 --> O3
    O2 -->|Streamable HTTP / SSE| MCP_O
    O3 --> APP

    MCP_C -->|OAuth 2.1 Token Validation| JWKS
    MCP_O -->|RS256 Bearer Check| JWKS

    MCP_C --> APP
    MCP_O --> APP

    APP --> DB
    APP --> SMS
    SCHED --> DB
    SCHED --> SMS

🚀 Key Innovations & Technical Pillars

1. Physical MCP Separation

Citizen Endpoint (/mcp/citizen): Exposes applicant-scoped tools (get_scheme_information, check_eligibility, get_my_application_status, submit_application, withdraw_application, download_acknowledgment, submit_grievance, list_schemes, get_required_documents). A citizen's assistant never receives officer tools in its schema.
Block Officer Endpoint (/mcp/officer): Exposes departmental administrative tools (get_officer_dashboard, list_pending_applications, get_application_details, approve_application, reject_application, search_applications, verify_documents, get_application_queue, get_welfare_analytics, update_application_status).
Cryptographic Access Control: Validates RS256 Bearer tokens against the server's public JWKS. Cross-role invocations immediately fail with 403 Forbidden (insufficient_scope).

2. Enterprise OAuth 2.1 & RFC 9728 Discovery

RFC 8414 Authorization Server Discovery: /.well-known/oauth-authorization-server
RFC 9728 Protected Resource Metadata: /.well-known/oauth-protected-resource
RFC 8707 Resource Indicators: Tokens carry aud matching the canonical URL and explicit scopes (citizen or officer).
RFC 7009 Token Revocation: /oauth/revoke
Session Caps: Hard session limit (2h for citizens on public kiosks; 8h for administrative officers) with rotating refresh tokens that never exceed the master session ceiling.

3. Persona-Driven PostgreSQL Invariant Evaluations

Unlike fragile synthetic LLM-as-a-judge scoring, SewaSetu AI features a rigorous invariant evaluation suite accessible at /eval-dashboard. It executes multi-turn dialogues across 7 authentic personas and verifies post-condition assertions directly against PostgreSQL:

Persona	Scenario	Invariant Asserted in Database
1. Rameswar Barman (64)	Valid first-time pension application	Record created in DB with status `PENDING`, age verified, certified PDF generated.
2. Minati Das (58)	Underage applicant attempt	60-year statutory threshold enforces rejection; zero database records created.
3. Bhaben Kalita (68)	Duplicate application attempt	Detects existing pending record; duplicate blocked; single active record maintained.
4. Anowara Khatun (66)	Re-application after voluntary withdrawal	State transitions from `PENDING` to `WITHDRAWN`; subsequent new application succeeds.
5. Prabhat Sarma (72) & Officer	End-to-end multi-agent workflow	Applicant submits; Block Officer reviews and transitions state to `APPROVED`.
6. Tarun Gogoi (65) & Officer	Officer rejection with audit trail	Application rejected with mandatory justification; applicant is unblocked for re-filing.
7. Statutory RTPS SLA	Automatic Deemed Approval Engine	Applications pending beyond 15-day SLA transition automatically to `DEEMED_APPROVED`.

4. Senior-First Accessible Web Portal

Accessibility Toolbar: On-screen quick toggles for font scaling (A- / A / A+) and High Contrast Dark Mode with preference persistence via localStorage.
Keyboard & Screen Reader Navigable: Semantic HTML, ARIA attributes, skip links, and zero focus trapping.
Multilingual Ready: Clean layouts accommodating Assamese, Hindi, and English scripts.

5. Statutory SLA & RTPS Deemed Approval Engine

Enforces the Right to Public Services (RTPS) 15-day statutory turnaround.
Nightly background scheduler identifies overdue applications and transitions them to DEEMED_APPROVED by RTPS-AUTO with instant beneficiary SMS dispatch.

🌐 Interactive Endpoints Directory

Category	Endpoint	Method / Protocol	Description	Auth Required
Portal	`/`	HTTP `GET`	Public Portal Homepage with live scheme highlights	None
Portal	`/status`	HTTP `GET` / `POST`	Citizen Application Status Lookup (Mobile + DoB DDMMYYYY)	None
Assistant	`/assistant`	HTTP `GET` / `POST`	In-browser Citizen AI Assistant with database grounding	None
Officer	`/admin`	HTTP `GET` / `POST`	Block Welfare Officer Dashboard and Application Queue	Session (`admin`)
Tokens	`/admin/tokens`	HTTP `GET` / `POST`	Programmatic OAuth Token Minting for Officer Agents	Session (`admin`)
Evaluations	`/eval-dashboard`	HTTP `GET`	Live Persona Invariant Evaluation Runner & Dashboard	None
MCP	`/mcp/citizen`	Streamable HTTP / SSE	Citizen Model Context Protocol Server (10 tools)	Bearer (`citizen`)
MCP	`/mcp/officer`	Streamable HTTP / SSE	Block Officer Model Context Protocol Server (10 tools)	Bearer (`officer`)
Discovery	`/.well-known/oauth-authorization-server`	HTTP `GET`	RFC 8414 Authorization Server Metadata	None
Discovery	`/.well-known/oauth-protected-resource`	HTTP `GET`	RFC 9728 Protected Resource Metadata	None
Discovery	`/.well-known/jwks.json`	HTTP `GET`	RS256 JWKS Public Key Set	None
SMS	`/__gateway/`	HTTP `GET`	Simulated SMS Gateway Console & Real-time Inbox	None
Ops	`/health`	HTTP `GET`	Operational Health Check (DB, Disk, Scheduler)	None

🛠️ MCP Toolsets Reference

get_scheme_information: Retrieve statutory rules, pension amounts, eligibility criteria, and required documents.
check_eligibility: Pre-screen applicant age, block residence, and bank eligibility.
get_my_application_status: Track live application status by Application ID or Mobile + DoB.
submit_application: Lodge a formal pension application with automated validation.
withdraw_application: Voluntarily cancel a pending application to permit re-application.
download_acknowledgment: Retrieve official certified PDF acknowledgment with digital seal.
submit_grievance: File an RTPS grievance regarding delayed processing or officer rejection.
list_schemes: Alias for scheme discovery across departments.
get_required_documents: Detailed document checklist for proof of age and bank account.
get_block_list: List eligible administrative blocks in the jurisdiction.

get_officer_dashboard: Summarize pending, approved, deemed approved, and overdue applications.
list_pending_applications: Retrieve priority queue sorted by submission date and SLA urgency.
get_application_details: Deep inspection of applicant records, age proofs, and bank details.
approve_application: Formally approve an application with mandatory verification remarks.
reject_application: Formally reject an application with specific statutory justification.
search_applications: Query applications by name, mobile, block, status, or date range.
verify_documents: Perform automated checks on uploaded age proofs (Voter ID, Aadhaar, etc.).
get_application_queue: Queue inspection with status filtering and pagination.
get_welfare_analytics: Comprehensive scheme performance metrics and block-wise distribution.
update_application_status: Generic status update wrapper with strict role enforcement.

⚡ Quick Start & Local Setup

Option A: Launch with Docker Compose (Recommended)

The complete stack includes the Flask web core, PostgreSQL 15 (seeded with 100k demo records), the simulated SMS gateway, and the RTPS scheduler:

# Clone the repository
git clone https://github.com/12636373/harish-sewasetu-ai.git
cd harish-sewasetu-ai

# Start the complete production stack
docker compose up -d --build

Access the services:

Public Portal: http://localhost:8000
Evaluation Dashboard: http://localhost:8000/eval-dashboard
Departmental Admin: http://localhost:8000/admin (Username: admin, Password: change-me-before-deploying)
SMS Gateway: http://localhost:8000/__gateway/

Option B: Native Python Setup

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Run with local SQLite fallback (or set POSTGRES_* environment variables)
export USE_SQLITE=1
export SECRET_KEY=development-secret-key
python app/app.py

🤖 Connecting Agent Clients

SewaSetu AI is fully compatible with any Model Context Protocol client including Claude Code, Cursor, Windsurf, and autonomous agents.

Claude Code Integration

# Connect to the Citizen MCP Server
claude mcp add sewasetu-citizen --transport http https://<YOUR-DOMAIN>/mcp/citizen

# Connect to the Administrative Officer MCP Server
claude mcp add sewasetu-officer --transport http https://<YOUR-DOMAIN>/mcp/officer

Cursor / Windsurf Configuration (`mcp.json`)

{
  "mcpServers": {
    "sewasetu-citizen": {
      "url": "http://localhost:8000/mcp/citizen",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <YOUR_CITIZEN_TOKEN>"
      }
    },
    "sewasetu-officer": {
      "url": "http://localhost:8000/mcp/officer",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <YOUR_OFFICER_TOKEN>"
      }
    }
  }
}

🧪 Test Suites & Quality Verification

SewaSetu AI includes a comprehensive, multi-tiered automated testing framework:

# 1. Run the standalone 8-step independent MCP verification suite
python verify_mcp_independent.py

# 2. Run backend business logic and database state machine tests
pytest tests/test_backend_logic.py -v

# 3. Execute live persona evaluations via CLI
python -c "from app.evals import run_all_evaluations; print(run_all_evaluations())"

📁 Directory Structure

harish-sewasetu-ai/
├── app/
│   ├── app.py                     # Main Flask application & routing
│   ├── mcp_server.py              # Segregated Citizen & Officer MCP servers
│   ├── evals.py                   # 7 Persona evaluation framework & invariant runner
│   ├── schema.sql                 # PostgreSQL relational schema
│   ├── scripts/
│   │   └── deemed_approval.py     # RTPS 15-day statutory deemed approval job
│   ├── static/                    # CSS, JavaScript, and asset files
│   └── templates/                 # Accessible Jinja2 UI templates
│       ├── base.html              # Layout with accessibility controls (A-/A/A+)
│       ├── index.html             # Scheme home & key metrics
│       ├── apply.html             # Application form
│       ├── status.html            # Public status tracking portal
│       ├── assistant.html         # Grounded Citizen AI Assistant
│       ├── admin_dashboard.html   # Officer triage queue
│       └── eval_dashboard.html    # Live evaluation dashboard
├── seed/
│   └── seed.sql                   # Initial database seed (100k records)
├── smsgw/                         # Simulated SMS gateway microservice
├── tests/
│   └── test_backend_logic.py      # Unit and integration test suite
├── docker-compose.yml             # Local multi-service orchestration
├── docker-compose.prod.yml        # Production deployment compose with Caddy
├── Caddyfile                      # Reverse proxy with automated Let's Encrypt SSL
├── verify_mcp_independent.py      # Standalone 8-step independent MCP test runner
├── wasmer.toml                    # Wasmer Edge runtime configuration
├── app.yaml                       # Wasmer Edge application manifest
├── LICENSE                        # MIT Open Source License
└── README.md                      # Project documentation

🔒 Security & Prompt Injection Defenses

SewaSetu AI enforces robust multi-layered defenses:

Separation of Concerns: Citizen assistants have zero access to officer tools in their schema.
Administrative Action Interception: Any prompt attempting to coerce a citizen assistant into approving applications or changing statuses is rejected with an explicit security warning.
Credential Protection: System instructions strictly forbid the disclosure of internal API keys, passwords, database credentials, or private keys.
Statutory Guardrails: Applications cannot be backdated or submitted outside established business and residency criteria.

👤 Author & License

Designed, architected, and built by Harish.

Released under the MIT License. Contributions, issues, and feature requests are welcome!