# omoshiro-mcp

Research-grounded MCP server for analyzing **interestingness / 面白さ**.

This server does **not** score content. It returns evaluation lenses, conceptual boundaries, interaction patterns, and research references so that the calling AI can perform the analysis itself.

## Principle

> Returns evaluation lenses; does not score content.

The ontology separates:

- **Primitive lenses**: constructs an AI can inspect directly or relative to an audience model
- **Derived dynamics**: changes over time such as prediction error or uncertainty reduction
- **Composite states/mechanisms**: interest, curiosity, suspense, humor, insight, flow, awe, transportation
- **Outcomes**: enjoyment, attention, memory, learning, persistence, etc.

This avoids collapsing everything into one meaningless `interestingness_score`.

## MCP endpoint

When deployed on Vercel, use:

```text
https://<your-project>.vercel.app/mcp
```

Protocol: MCP Streamable HTTP / JSON-RPC.

## Tools

### `get_lenses`
Returns a curated set of primitive lenses for a target.

Example arguments:

```json
{
  "target_type": "oogiri",
  "analysis_goal": "humor"
}
```

### `search_lenses`
Searches primitive and composite constructs by natural-language terms.

```json
{
  "query": "unexpected but understandable"
}
```

### `get_lens`
Returns the definition, diagnostic questions, conceptual boundaries, applicability, and inferability of a primitive lens.

```json
{"id":"novelty"}
```

### `get_composite`
Returns a composite mechanism/state and its input constructs.

```json
{"id":"suspense"}
```

### `list_ontology`
Lists the full ontology and core references.

## Core primitive lenses

Current v0.1 includes 21 primitives:

- novelty
- complexity
- comprehensibility
- processing_fluency
- relevance
- information_gap
- knowability
- uncertainty
- expectation_strength
- outcome_significance
- conflict_instability
- violation
- benignness
- vastness
- accommodation_demand
- challenge
- competence
- control
- autonomy
- feedback_clarity
- relatedness

## Derived dynamics

- prediction_error
- information_gain
- uncertainty_reduction
- gap_resolution
- conflict_resolution
- comprehension_gain
- fluency_gain
- mastery_progress

## Composite mechanisms / states

- interest
- curiosity
- suspense
- humor_benign_violation
- humor_incongruity_resolution
- insight
- flow
- awe
- transportation

A composite is **not** a score. For example:

```text
Interest ≈ novelty/complexity × sufficient comprehensibility
Curiosity ≈ information gap × knowability × relevance × uncertainty
Suspense ≈ uncertainty × expectation strength × outcome significance
Benign-violation humor ≈ violation × benignness
Awe ≈ vastness × accommodation demand
```

These are conceptual patterns, not validated universal equations.

## Inferability

Each lens includes an `inferability` field:

- `direct`: can often be inspected from the content itself
- `audience_model_required`: depends on prior knowledge, culture, genre expectations, etc.
- `experience_required`: actual psychological state should not be asserted without audience/player evidence

For example, `novelty` is audience-relative, while actual `flow` or `transportation` cannot be reliably asserted just by reading the artifact.

## Example workflow

User asks:

> こんなエンジニアは嫌だ。どんなエンジニア？  
> 回答：キーボードがでかすぎて部屋に入らない

Calling AI:

1. calls `get_lenses({ target_type: "oogiri", analysis_goal: "humor" })`
2. receives lenses such as `expectation_strength`, `violation`, `benignness`, `novelty`, `comprehensibility`, `processing_fluency`
3. performs the actual analysis itself
4. does **not** ask the MCP to output a humor score

## Research basis

The v0.1 ontology is informed by work including:

- Silvia, P. J. (2005). *What Is Interesting? Exploring the Appraisal Structure of Interest*. Emotion.
- Loewenstein, G. (1994). *The Psychology of Curiosity: A Review and Reinterpretation*. Psychological Bulletin.
- Kang, M. J. et al. (2009). *The Wick in the Candle of Learning: Epistemic Curiosity Activates Reward Circuitry and Enhances Memory*. Psychological Science.
- Reber, R., Schwarz, N., & Winkielman, P. (2004). *Processing Fluency and Aesthetic Pleasure*. Personality and Social Psychology Review.
- McGraw, A. P. & Warren, C. (2010). *Benign Violations: Making Immoral Behavior Funny*. Psychological Science.
- Keltner, D. & Haidt, J. (2003). *Approaching Awe, a Moral, Spiritual, and Aesthetic Emotion*. Cognition and Emotion.
- Ryan, R. M., Rigby, C. S., & Przybylski, A. (2006). *The Motivational Pull of Video Games*. Motivation and Emotion.
- Busselle, R. & Bilandzic, H. (2009). *Measuring Narrative Engagement*. Media Psychology.

The ontology is an engineering synthesis across these literatures, not a claim that one paper defines the complete structure.

## Development

The server is intentionally dependency-light and implemented as a Vercel serverless endpoint in `api/mcp.js`.

A GET request to `/mcp` returns server metadata. MCP clients should use POST JSON-RPC requests for `initialize`, `tools/list`, and `tools/call`.

## License

MIT